Amazon AI Transcreation Platform

An AI-powered platform for transcreating marketing content across European locales. Built for Amazon's creative workflows, it combines Claude LLM capabilities with translation memory, glossaries, and brand voice profiles to produce culturally adapted copy at scale.

Tech Stack

Layer	Technology
Frontend	Next.js 14, React 18, Tailwind CSS, Radix UI
Backend	FastAPI, Python 3.12, SQLAlchemy 2 (async)
Database	PostgreSQL 16
Cache/Queue	Redis 7, Celery
LLM	Anthropic Claude (via API)
Infra	Docker, Docker Compose

Prerequisites

• Docker and Docker Compose v2
• An Anthropic API key for Claude access

Quick Start

# 1. Clone the repository
git clone <repo-url> amazon-transcreation
cd amazon-transcreation

# 2. Configure environment
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY, JWT_SECRET_KEY

# 3. Start all services
docker compose up -d

# 4. Run database migrations
make migrate

# 5. Seed the database with the Amazon client
make seed

# 6. Open the app
# Backend API docs:  http://localhost:8000/docs
# Frontend:          http://localhost:3000

Architecture

+---------------------------------------------------------------+
|                        Frontend (Next.js)                      |
|  Dashboard  |  Job Builder  |  Review UI  |  TM Manager       |
+-------------------------------+-------------------------------+
               |  REST + WebSocket  |
+-------------------------------+-------------------------------+
|                       Backend (FastAPI)                        |
|  Auth  |  Jobs API  |  TM API  |  Files API  |  WebSocket     |
+-------------------------------+-------------------------------+
               |                    |
+--------------+------+    +-------+----------------------------+
|   PostgreSQL        |    |  Celery Workers                    |
|   - clients         |    |  - LLM transcreation tasks         |
|   - users           |    |  - TM lookup & scoring             |
|   - jobs            |    |  - File processing                 |
|   - source_lines    |    +------------------------------------+
|   - output_rows     |               |
|   - feedback        |    +----------+-------------------------+
|   - tm_file_registry|    |  Claude API (Anthropic)            |
|   - reference_files |    |  - Transcreation generation        |
|   - audit_logs      |    |  - Quality scoring                 |
+---------------------+    +------------------------------------+
               |
+---------------------+
|   Storage (volume)   |
|   - TM files (JSONL) |
|   - Reference files   |
+---------------------+

Development

Backend

# Shell into the backend container
make shell

# Run tests
make test

# View logs
make logs

# Access the database
make db-shell

Frontend

cd frontend
npm install
npm run dev

The frontend dev server runs on port 3000 and proxies API requests to the backend on port 8000.

Running Tests

# Backend tests (inside Docker)
make test

# Frontend tests
cd frontend && npm run lint

API Documentation

FastAPI auto-generates interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Project Structure

amazon-transcreation/
├── backend/
│   ├── alembic/              # Database migrations
│   ├── app/
│   │   ├── api/v1/           # REST API routes
│   │   ├── models/           # SQLAlchemy models
│   │   ├── schemas/          # Pydantic request/response schemas
│   │   ├── services/         # Business logic
│   │   ├── tasks/            # Celery async tasks
│   │   ├── ws/               # WebSocket handlers
│   │   ├── config.py         # Settings from environment
│   │   ├── dependencies.py   # FastAPI dependency injection
│   │   └── main.py           # Application factory
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── public/               # Static assets, fonts
│   ├── src/                  # Next.js pages and components
│   ├── Dockerfile
│   └── package.json
├── scripts/
│   ├── tm_format_migrator.py # Convert compact TM to multi-field JSONL
│   └── validate_tm_files.py  # Audit TM files for format and coverage
├── seed/
│   ├── create_default_client.py  # Seed Amazon client + voice profiles
│   └── import_reference_files.py # Import TMs and refs to storage/
├── storage/                  # Mounted volume for TM and reference files
├── .env.example              # Environment variable template
├── docker-compose.yml        # Service orchestration
├── Makefile                  # Development shortcuts
└── README.md

Key Concepts

• Client: An organization (e.g., Amazon) with voice profiles, supported locales, and channel configurations stored as JSON settings.
• Voice Profile: Brand personality (Retail, Prime, Brand) that guides tone and style during transcreation.
• Channel: A content distribution context (Mass TV, Onsite, etc.) with its own translation memory.
• Translation Memory (TM): JSONL files of previously approved source/target pairs, used for context and consistency.
• Reference Files: Glossaries, blacklists, date/percent format guides, and locale-specific considerations that constrain the LLM output.

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL async connection string	postgresql+asyncpg://...
REDIS_URL	Redis connection string	redis://redis:6379/0
ANTHROPIC_API_KEY	Anthropic API key for Claude	(required)
JWT_SECRET_KEY	Secret for signing JWT tokens	(required, change default)
JWT_ALGORITHM	JWT signing algorithm	HS256
JWT_EXPIRY_HOURS	Token expiry in hours	8
STORAGE_ROOT	Root path for file storage	/storage
LLM_MODEL	Claude model identifier	claude-sonnet-4-20250514