Skip to content

Deployment Overview

This guide provides an overview of deploying the New Hires Reporting system to a production environment.

System Architecture

The New Hires Reporting system is a containerized application that processes and corrects fixed-width formatted files using AWS Bedrock AI. The system consists of four main services:

Services

  1. PostgreSQL Database

    • Stores correction jobs and job queue
    • Persistent data storage using Docker volumes
    • Port: 5432 (internal)

  2. Backend API (FastAPI)

    • REST API for file conversion and job management
    • Handles file parsing, validation, and building
    • Python 3.11 with FastAPI framework
    • Port: 8000

  3. Workers

    • Background job processor
    • Polls job queue and processes AI correction jobs
    • Uses AWS Bedrock for intelligent error correction
    • Configurable concurrency and retry logic
    • No exposed ports (internal service)

  4. Frontend (React + Nginx)

    • Modern web interface built with React 19
    • Nginx web server for production
    • Proxies API requests to backend
    • Port: 8080

Architecture Diagram

┌─────────────────┐
│    Frontend     │ Port 8080
│  React + Nginx  │ (Web Interface)
└────────┬────────┘
         │
         │ HTTP Requests
         ↓
┌─────────────────┐     ┌──────────────────┐
│   Backend API   │────→│   PostgreSQL     │
│    FastAPI      │     │    Database      │
│                 │←────│  (Jobs & Queue)  │
└────────┬────────┘     └────────┬─────────┘
         │                       ↑
    Port 8000                    │
         │                       │
         │                 Poll Queue
         │                       │
         │               ┌───────┴────────┐
         │               │    Workers     │
         └──────────────→│  (Background   │
           Job Results   │   Processor)   │
                         └────────┬───────┘
                                  │
                                  │ API Calls
                                  ↓
                         ┌─────────────────┐
                         │  AWS Bedrock    │
                         │  (Claude AI)    │
                         │   us-east-1     │
                         └─────────────────┘

Data Flow

  1. User uploads file → Frontend sends to Backend API
  2. Backend validates file → Identifies validation errors
  3. Backend creates correction job → Inserts into job queue (PostgreSQL)
  4. Worker polls queue → Picks up pending jobs
  5. Worker processes job → Calls AWS Bedrock with validation errors
  6. Bedrock returns corrections → Worker applies corrections to file
  7. Worker validates result → Ensures corrections fixed the errors
  8. Worker stores result → Saves corrected file to database
  9. User downloads corrected file → Frontend retrieves from Backend API

Deployment Requirements

Infrastructure Requirements

  • Server/Host: Linux server (Ubuntu 22.04+ recommended) or any Docker-capable host
  • RAM: Minimum 4 GB (8 GB recommended for production)
  • Disk Space: 20 GB minimum (more if processing large volumes)
  • Network: Outbound internet access to AWS services (us-east-1 region)

Software Requirements

  • Docker: Version 20.10 or higher
  • Docker Compose: Version 2.0 or higher
  • AWS CLI: Optional but recommended for ECR authentication

AWS Requirements

  • AWS Account with active subscription
  • AWS Bedrock access enabled in us-east-1 region
  • Model Access:
    • Claude Sonnet 4.5 (us.anthropic.claude-sonnet-4-5-20250929-v1:0)
    • Llama 4 Scout (optional: us.meta.llama4-scout-17b-instruct-v1:0)
  • IAM Credentials with permissions:
    • bedrock:InvokeModel on specified models
    • ECR pull access (for image deployment)

Network Requirements

  • Inbound Ports:
    • 8080 (Frontend web interface)
    • 8000 (Backend API - optional, can be internal only)
  • Outbound Access:
    • HTTPS to AWS Bedrock API (us-east-1)
    • HTTPS to AWS ECR (us-east-1)
    • DNS resolution

Deployment Methods

Method: Docker Compose with pre-built ECR images

Best for: Production environments, client deployments

Steps: 1. Authenticate to AWS ECR 2. Pull pre-built images from ECR registry 3. Configure environment variables (AWS credentials, etc.) 4. Start services with docker-compose.prod.yml 5. Run database migrations

Documentation: See Docker Compose Deployment

Development Deployment

Method: Docker Compose with local builds and hot-reload

Best for: Development and testing

Steps: 1. Build images locally 2. Start services with docker-compose.yml 3. Code changes auto-reload in containers

Note: Development deployment is not covered in this documentation as it's focused on production deployment for clients.

Key Differences from Previous Version

Important Changes

This is a completely refactored system. Key changes include:

  • Frontend: Changed from Streamlit to React + Nginx
  • AI Provider: Changed from OpenRouter to AWS Bedrock
  • Database: Added PostgreSQL for job persistence
  • Workers: New background job processing service
  • Integrations Removed: Mapbox and Zendesk integrations have been removed

Deployment Checklist

Before deploying, ensure you have completed:

  • [ ] Docker and Docker Compose installed on server
  • [ ] AWS account with Bedrock access enabled
  • [ ] IAM credentials created with correct permissions (see AWS Bedrock setup)
  • [ ] ECR authentication configured
  • [ ] .env file created with required variables
  • [ ] Network ports opened (8080 for web access)
  • [ ] Backup strategy planned for PostgreSQL data

Networking

Service Communication

  • Frontend → Backend: Internal API calls proxied through Nginx
  • Backend → Database: Direct PostgreSQL connection
  • Workers → Database: Polls job queue and updates job status
  • Workers → AWS: HTTPS API calls to Bedrock service

Port Exposure

Service Internal Port External Port Purpose
Frontend 80 8080 Web interface
Backend 8000 8000 REST API
Database 5432 - PostgreSQL (internal only)
Workers - - Background processor (no ports)

Security

  • Database is not exposed externally
  • Workers run as internal service only
  • Backend API can be restricted to internal network if desired
  • Frontend uses Nginx as reverse proxy for API calls

Storage

Persistent Volumes

postgres-data: Database storage

  • Location: Docker volume (newhires-reporting_postgres-data)
  • Purpose: PostgreSQL database files, correction jobs, job queue
  • Persistence: Survives container restarts and updates
  • Backup: Should be backed up regularly (see Operations Guide)

Next Steps

  1. AWS Bedrock Setup - Configure AWS and create IAM credentials
  2. Docker Compose Deployment - Deploy the application
  3. Environment Variables - Configure your environment
  4. Health Monitoring - Monitor your deployment

Estimated Deployment Time

  • First-time deployment: 30-60 minutes
  • Updates/upgrades: 10-15 minutes

Support

For issues during deployment:

  1. Check Common Issues
  2. Review service logs: docker-compose -f docker-compose.prod.yml logs
  3. Verify AWS credentials and Bedrock access
  4. Contact technical support with detailed error messages