---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/security
- tech/azure-ad
- tech/celery
- tech/claude
- tech/docker
- tech/fastapi
- tech/nextjs
- tech/postgresql
- tech/react
- tech/redis
type: sop
---

# Amazon AI Transcreation Platform - Developer Manual

## Architecture Overview

The platform consists of:
1. **Frontend**: Next.js 14 application with React components, handling UI/UX, authentication, and real-time job polling.
2. **Backend**: FastAPI application providing REST APIs for Auth, Jobs, and Output management.
3. **Database**: PostgreSQL 16 for storing job metadata, user data, and output references.
4. **Cache/Queue**: Redis 7 for task queue management (Celery) and caching.
5. **Task Workers**: Celery workers processing transcreation jobs asynchronously.
6. **LLM Integration**: Anthropic Claude API for AI-driven transcreation.

```
Frontend (Next.js) <--> FastAPI Backend <--> Celery Workers
      |                         |                    |
      |                         |                    V
      |                         |              PostgreSQL
      |                         |              Redis
      |                         |
      +-------------------------+-----------------+
                              |
                         Claude LLM API
```

## Tech Stack

- **Frontend**: Next.js 14, React, Tailwind CSS, Radix UI Components
- **Backend**: Python, FastAPI, Uvicorn
- **Database**: PostgreSQL 16 (asyncpg)
- **Queue/Caching**: Redis 7, Celery
- **LLM**: Anthropic Claude (`claude-sonnet-4-6`)
- **Authentication**: JWT, Azure AD SSO (optional)
- **Deployment**: Docker, Docker Compose

## Local Setup

### Prerequisites
- Docker and Docker Compose
- Python 3.11+ (for local dev if needed)
- Anthropic API Key

### Steps
1. **Clone the repository**.
2. **Configure Environment**:
   ```bash
   cp .env.example .env
   ```
   Update `.env` with your values (especially `ANTHROPIC_API_KEY` and `JWT_SECRET_KEY`).

3. **Start Services**:
   ```bash
   docker-compose up -d
   ```
   This starts:
   - `db` on port `5492`
   - `redis` on port `6389`
   - `backend` on port `8040`
   - `frontend` (via Next.js dev server in Docker or separate setup)
   - `celery_worker` on port `8041` (if exposed)

4. **Run Migrations** (if applicable):
   Ensure database tables are created. Check backend Dockerfile for init scripts.

5. **Access the Platform**:
   - Frontend: `http://localhost:3000` (or mapped port)
   - Backend API: `http://localhost:8040`

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | `postgresql+asyncpg://transcreation:transcreation@db:5432/transcreation` |
| `REDIS_URL` | Redis connection string | `redis://redis:6379/0` |
| `ANTHROPIC_API_KEY` | Anthropic API key | `sk-ant-xxxxx` |
| `JWT_SECRET_KEY` | Secret for JWT signing | `CHANGE_ME_TO_A_RANDOM_SECRET` |
| `JWT_ALGORITHM` | JWT algorithm | `HS256` |
| `JWT_EXPIRY_HOURS` | Token expiry | `8` |
| `STORAGE_ROOT` | Path for file storage | `/storage` |
| `LLM_MODEL` | Model to use | `claude-sonnet-4-6` |
| `AZURE_AD_SSO_ENABLED` | Enable Azure AD SSO | `true/false` |
| `AZURE_AD_TENANT_ID` | Azure AD Tenant ID | (if SSO enabled) |
| `AZURE_AD_CLIENT_ID` | Azure AD Client ID | (if SSO enabled) |

## Key Services & Entry Points

### Backend (`backend/`)
- **Main App**: `app/main.py` - FastAPI application entry point.
- **Tasks**: `app/tasks/celery_app.py` - Celery app configuration.
- **Database Models**: Likely in `app/models/` (PostgreSQL via SQLAlchemy/asyncpg).
- **Storage**: Files stored in `/storage` (mounted in Docker).

### Frontend (`frontend/`)
- **Layout**: `src/app/layout.tsx` - Root layout with Amazon Ember font.
- **Auth**: `src/lib/auth.ts` - Authentication utilities (`isAuthenticated`).
- **Components**: Radix UI components in `src/components/ui/`.
- **Pages**:
  - `src/app/page.tsx` - Redirects to `/dashboard` or `/login`.
  - `src/app/dashboard/` - Job Wizard, Monitor, Review.

### Docker Compose (`docker-compose.yml`)
- **db**: PostgreSQL 16, healthcheck via `pg_isready`.
- **redis**: Redis 7 Alpine, healthcheck via `redis-cli ping`.
- **backend**: Uvicorn server, mounts `./backend` for live reload.
- **celery_worker**: Celery worker, `--concurrency=4`.

## API Reference

- **Auth Endpoints**: `/auth/login`, `/auth/refresh` (JWT-based).
- **Jobs Endpoints**:
  - `POST /jobs` - Create new transcreation job.
  - `GET /jobs` - List jobs.
  - `GET /jobs/{job_id}` - Get job details/status.
  - `POST /jobs/{job_id}/approve` - Approve job output.
- **Output Endpoints**:
  - `GET /output/{job_id}` - Download final translations.
- **Healthcheck**:
  - `GET /health` - Check service health.

*Note: Exact endpoints depend on implementation in `app/api/`. Polling interval in frontend is 3 seconds for job status updates.*

## Deployment

### Production Checklist
1. **Set Production Env Vars**: Ensure all secrets are secure. Disable `--reload` in Uvicorn.
2. **Disable Dev Volumes**: Remove `./backend:/app` mounts in production Dockerfile.
3. **Enable Azure AD SSO**: Set `AZURE_AD_SSO_ENABLED=true` and provide credentials.
4. **Secure Storage**: Ensure `/storage` is on persistent, secure storage.
5. **Monitoring**: Set up logging and monitoring for Celery workers and PostgreSQL.
6. **Reverse Proxy**: Use Nginx/Traefik to handle HTTPS and route traffic to the backend/frontend.

## Known Gotchas

- **Port Mappings**: In Docker Compose, ports are remapped (e.g., `5492:5432`). Ensure no conflicts.
- **Volume Mounts**: During dev, `./backend:/app` allows hot-reload. Do not use this in production as it can cause permission issues.
- **JWT Secrets**: Never commit `JWT_SECRET_KEY` to version control. Use secret management tools in production.
- **LLM Costs**: Anthropic API calls can be costly. Monitor usage and set limits if necessary.
- **Celery Concurrency**: Default is 4 workers. Adjust based on load and available resources.
- **Database Healthcheck**: If DB is slow, adjust `healthcheck` intervals in `docker-compose.yml`.
- **Font Files**: Amazon Ember fonts are embedded in the frontend. Ensure they are licensed for use.
- **Redis/PostgreSQL**: Ensure both services are healthy before starting backend/celery. `depends_on` with `condition: service_healthy` helps, but add retries in app code.

## Related
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/enterprise-ai-hub-nexus/DEVELOPER_MANUAL.md]]
- [[01 Projects/oliver-ai-assistant/DEVELOPER_MANUAL.md]]
- [[01 Projects/Oliver-ai-bot_2.0/DEVELOPER_MANUAL.md]]
- [[01 Projects/amazon-transcreation/USER_MANUAL.md]]
- [[01 Projects/oliver-sales-ops-platform/DEVELOPER_MANUAL.md]]