# 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](https://docs.docker.com/get-docker/) and Docker Compose v2
- An [Anthropic API key](https://console.anthropic.com/) for Claude access

## Quick Start

```bash
# 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

```bash
# Shell into the backend container
make shell

# Run tests
make test

# View logs
make logs

# Access the database
make db-shell
```

### Frontend

```bash
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

```bash
# 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](http://localhost:8000/docs)
- **ReDoc**: [http://localhost:8000/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`   |