obsidian/01 Projects/amazon-transcreation/Amazon Transcreation.md

name	client	status	server	tech	local_path	deploy	url	tags	created	port	db
Amazon Transcreation	Amazon	active	local	Next.js 14 FastAPI Python PostgreSQL Redis Celery Claude LLM	/Users/ai_leed/Documents/Projects/Oliver/amazon-transcreation	docker compose up -d		project	2026-04-15	8040	PostgreSQL

Overview

Amazon AI Transcreation Platform is an AI-powered web application that adapts Amazon marketing copy across 12 European locales using Claude LLM agents. It replaces a manual LibreChat workflow with a structured, one-click multi-locale processing system featuring real-time monitoring, in-app review capabilities, and proper job/file management. The platform orchestrates transcreation jobs through a Celery task queue, providing a dashboard for users to submit copy, track progress, review agent-generated translations, and manage translation memory (TM) and reference libraries.

Tech Stack

• Frontend: Next.js 14, React, TypeScript, Tailwind CSS
• Backend: FastAPI (Python), Pydantic, SQLAlchemy (async), Alembic migrations
• Database: PostgreSQL 16 (primary), Redis 7 (task queue & caching)
• Infrastructure: Docker Compose, Celery (4 concurrent workers)
• AI/ML: Anthropic Claude (default: claude-sonnet-4-6), LLM agent pipeline with multi-stage processing
• Key libraries: python-multipart, httpx, jose (JWT auth), Azure AD MSAL (SSO)

Architecture

The platform follows a task-queue-driven microservices pattern:

┌─────────────────┐
│  Next.js 14     │  (http://localhost:3000)
│  (Dashboard UI) │
└────────┬────────┘
         │ HTTP REST
         │ (3-sec polling)
         ▼
┌──────────────────────────────┐
│   FastAPI Backend            │  (http://localhost:8040)
│  ┌──────────────────────────┐│
│  │ Auth / Jobs / Output API ││
│  └────────────┬─────────────┘│
└───────────────┼──────────────┘
                │
                ▼
        ┌───────────────┐
        │  Redis Queue  │
        │  (Celery)     │
        └───────┬───────┘
                │
                ▼
    ┌─────────────────────┐
    │ Celery Workers (×4) │
    │                     │
    │ VALIDATE ──►        │
    │ SINGLE_AGENT ──►    │
    │ FORMAT ──►          │
    │ DONE                │
    └─────────────────────┘
                │
                ▼
        ┌───────────────┐
        │  PostgreSQL   │
        │  (Job state)  │
        └───────────────┘

Key Design Decisions:

• Single LLM Agent Pipeline: Replaces multi-agent flow with one optimized Claude call using full V25 prompt (validation, transcreation, formatting in one go)
• Async-first Backend: Uses asyncpg for non-blocking database calls
• Job/File Management: Each transcreation request creates a job with associated input/output files stored on disk (/storage)
• Real-time Monitoring: Frontend polls every 3 seconds for job status updates
• Auth: JWT tokens with Azure AD SSO support (optional)
• Locale Support: 12 European locales (mapped to Amazon sales channels) + multi-channel TM routing

Dev Commands

# Start all services (DB, Redis, Backend, Celery worker)
make up

# Stop all services
make down

# Rebuild containers
make build

# Run database migrations
make migrate

# Seed default client & test users
make seed

# Run tests
make test

# View logs (all services)
make logs

# Access backend shell
make shell

# Direct DB access
make db-shell

# Direct Redis CLI
make redis-cli

# Restart backend & worker (after code changes)
make restart

Deployment

• Server: Local development only (docker-compose)
• Deploy: docker compose up -d
• URL: http://localhost:3000 (frontend), http://localhost:8040 (backend)
• Port: 8040 (FastAPI), 3000 (Next.js frontend)
• Service: Docker Compose (no systemd service configured)
• Local path: /Users/ai_leed/Documents/Projects/Oliver/amazon-transcreation

Environment Variables

Key configuration in .env.example:

• DATABASE_URL — PostgreSQL connection string (async driver required: +asyncpg)
• REDIS_URL — Redis connection for Celery task queue
• ANTHROPIC_API_KEY — Claude API key (required; format: sk-ant-...)
• JWT_SECRET_KEY — Secret for signing JWT tokens (change in production)
• JWT_ALGORITHM — Token algorithm (default: HS256)
• JWT_EXPIRY_HOURS — Token expiry window (default: 8 hours)
• STORAGE_ROOT — Path to job file storage (default: /storage)
• LLM_MODEL — Claude model version (default: claude-sonnet-4-6)
• AZURE_AD_TENANT_ID — Azure AD tenant (optional for SSO)
• AZURE_AD_CLIENT_ID — Azure AD client ID (optional for SSO)
• AZURE_AD_SSO_ENABLED — Enable/disable Azure AD authentication (default: false)

API / Endpoints

Key routes (all on http://localhost:8040):

• POST /api/auth/login — User login (JWT)
• POST /api/jobs — Create transcreation job
• GET /api/jobs/{job_id} — Fetch job status & progress
• GET /api/jobs/{job_id}/output — Retrieve completed output file
• POST /api/jobs/{job_id}/rerun_locale — Re-run a failed locale
• GET /api/tm-registry — List translation memory entries
• POST /api/tm-registry/upload — Upload TM file
• GET /api/reference-library — List reference documents
• POST /api/users — Create/manage users (admin)

(Full OpenAPI docs at GET /docs)

Known Issues

• ORM State: Recent fix (commit 710d931) resolves 500 errors on user updates by refreshing ORM object after database flush
• Dialog Warnings: Fixed in latest commit; ensure frontend re-renders after async operations
• Markdown Parser: Fixed (commit d5fa4e4) to preserve backtranslations and rationales in TM output; verify model selection doesn't break parsing
• TM Type Mismatch: Fixed (commit 2c7677b) to accept both list and dict for tm_entries_cited
• Azure AD SSO: Optional feature; only enable if tenant/client IDs configured
• Concurrency: Limited to 4 Celery workers; scale up in docker-compose.yml if bottleneck detected

Git

• Remote: git@bitbucket.org:zlalani/amazon-transcreation.git
• Branch: (check current with git branch)
• Latest commit: 710d931 — Fix 500 on user update: refresh ORM object after flush, fix dialog warnings
• Deployment branch: (check with team; likely main or develop)

Sessions

2026-04-16 – Fix 500 error when updating users

Asked: Fix 500 error when updating users and resolve accessibility warnings in the user form dialog. Done: Added database refresh after flush to resolve server-generated field issues, wrapped form fields in form element, and added aria-describedby to DialogContent.

2026-04-16 – Fix DialogContent missing Description warning and

Asked: Fix DialogContent missing Description warning and password field not in form error. Done: Added DialogDescription to DialogContent and wrapped password field in form element.

2026-04-15 – Implement user management with DB registration

Asked: Implement user management with DB registration and role assignment (viewer default, upgradeable to admin/manager). Done: Added user registration logic with role-based access control, deployed to production, and provided migration/seeding commands.

2026-04-15 – Implement user registration with DB persistence

Asked: Implement user registration with DB persistence and role management (default viewer, upgradeable to admin/manager). Done: Added viewer role to UserRole enum, updated SSO auto-provisioning, created migration, and deployed with admin seeding script.

2026-04-15 – Implement user registration in DB with

Asked: Implement user registration in DB with default viewer role and ability to upgrade to admin/manager via backend. Done: Added viewer role to UserRole enum, created migration, updated SSO auto-provisioning to assign viewer role by default, and verified all changes in git.

2026-04-15 – Implement user registration with DB persistence

Asked: Implement user registration with DB persistence and role management (default viewer, upgradeable to admin/manager). Done: Verified user registration logic integrates with existing role enums and confirmed all role references work correctly across jobs page and migration files.

2026-04-15 – Set up SSO (SPA) token exchange

Asked: Set up SSO (SPA) token exchange in the browser with Azure AD / MSAL configuration. Done: Added Azure AD environment variables to Docker configuration, updated deploy script, and pushed changes to Git.

2026-04-15 – Set up SSO (SPA) token exchange

Asked: Set up SSO (SPA) token exchange in the browser with Azure AD / MSAL configuration. Done: Added Azure AD environment variables to Dockerfile and docker-compose.prod.yml, configured Next.js build args for MSAL.

2026-04-15 – Set up SSO (SPA) token exchange

Asked: Set up SSO (SPA) token exchange in the browser with Azure AD/MSAL configuration. Done: Configured Azure AD credentials, updated deployment script, and added SSO setup to compose file and Dockerfile.

2026-04-15 – Set up SSO token exchange in

Asked: Set up SSO token exchange in the browser using Azure AD and MSAL. Done: Configured MSAL v5 with Azure AD credentials and removed deprecated storeAuthStateInCookie parameter to resolve type errors.

Change Log

Date	Requested	Changed	Files
2026-04-16	Fix user update errors and form warnings	Added refresh() after flush, wrapped fields in form element, added aria-describedby	backend/app/api/v1/users.py, frontend/src/app/admin/users/page.tsx
2026-04-16	DialogContent and password field accessibility	Added DialogDescription, wrapped input in form element	DialogContent.tsx, PasswordField.tsx
2026-04-15	User registration and role management	User model with role enum, migration for viewer role, admin seeding script	User.py, alembic migrations, create_default_admins.py
2026-04-15	User registration and roles	Added viewer role enum, SSO auto-provision logic, migration for role enum, admin seeding script	user.py, service.py, user.py schema, d3e4f5a6b7c8_add_viewer_role.py
2026-04-15	User registration with roles	Added viewer role enum value, created migration for viewer role, updated SSO service to default new users to viewer role	user.py, d3e4f5a6b7c8_add_viewer_role.py, service.py, user.py
2026-04-15	User registration and roles	Database persistence, default viewer role, admin/manager upgrade capability, role enum integration	jobs/[jobId]/page.tsx, migration file, seed script
2026-04-15	SSO/Azure AD setup	Added NEXT_PUBLIC_AZURE_AD_TENANT_ID, NEXT_PUBLIC_AZURE_AD_CLIENT_ID, SSO_ENABLED env vars to Docker build args, updated deploy script	frontend/Dockerfile, docker-compose.prod.yml, deploy.sh
2026-04-15	SSO setup with Azure AD	Added ARG and ENV for NEXT_PUBLIC_AZURE_AD_TENANT_ID, NEXT_PUBLIC_AZURE_AD_CLIENT_ID, SSO_ENABLED; updated build args in compose	frontend/Dockerfile, docker-compose.prod.yml
2026-04-15	SSO Azure AD setup	Added AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_REDIRECT_URI, updated deploy script, added setup summary	docker-compose.yml, Dockerfile, deploy.sh
2026-04-15	SSO/MSAL setup	Azure tenant/client ID configuration, removed storeAuthStateInCookie, token exchange flow	MSAL config file, authentication module

Related