# Translate Press Zone Backend - Comprehensive Implementation Plan

## 1. Executive Summary
**Goal**: High-performance translation API powering the WordPress plugin.
**Capabilities**: Sync translation (small), Async (large), batch processing, billing.
**AI Models**: Google Gemini API (gemini-3-flash-preview).
**Target**: Enterprise customers processing millions of tokens.

---

## 2. Technical Architecture

### 2.1 Stack Overview
- **Runtime**: Node.js 20 (TypeScript 5.x)
- **Framework**: Express.js 4.x
- **Database**: PostgreSQL 15 + Prisma ORM
- **Queue**: Redis 7.x + Bull (for async jobs and webhooks)
- **Translation**: Google Gemini API (gemini-3-flash-preview)
- **Admin Panel**: React 18 + Vite + TanStack Query

### 2.2 System Diagram
```
WordPress Plugin (Client)
       │
       ▼
   Load Balancer (Nginx)
       │
       ▼
  Node.js API Cluster ◄────► Redis (Cache/Queue)
       │                           │
       ▼                           ▼
   PostgreSQL (Data)      Google Gemini API
```

### 2.3 Database Schema (Prisma)

#### Core Entities
1. **User**: Account management, email, password hash.
2. **ApiKey**: SHA-256 hashed keys for plugin access.
3. **Subscription**: Plan tier (Starter, Pro, Enterprise).
4. **TranslationJob**: Async job tracking (pending, processing, completed).
5. **CreditTransaction**: Ledger for token usage and billing.
6. **WebhookDelivery**: Log of callbacks to WordPress.
7. **AuditLog**: Security and compliance tracking.

#### Schema Definition (Key Tables)
```prisma
model TranslationJob {
  id            String   @id @default(uuid())
  user_id       String
  status        String   @default("pending") // pending, processing, completed, failed
  source_lang   String
  target_lang   String
  content       String   @db.Text
  translation   String?  @db.Text
  tokens_used   Int      @default(0)
  tone          String   @default("neutral") // 'formal', 'casual', 'neutral'
  created_at    DateTime @default(now())
  completed_at  DateTime?
}

model CreditTransaction {
  id            String   @id @default(uuid())
  user_id       String
  amount        Int      // Positive (alloc) or Negative (usage)
  balance_after Int
  type          String   // 'usage', 'allocation', 'refund'
  reference_id  String?  // Job ID or Payment ID
}
```

---

## 3. Core Features & Implementation

### 3.1 Authentication & Security
- **API Keys**: Issued to WordPress plugins. Hashed storage (SHA-256).
  - Format: `sk_live_{32_random_chars}`
  - Rate Limit: 1000 req/hour per key (Redis-backed).
- **JWT**: For Admin Panel access (15min access, 7d refresh).
- **Input Validation**: Zod schemas for ALL endpoints.

### 3.2 Job Processing (Async Engine)
- **Queue**: `translation-jobs` (Bull).
- **Flow**:
  1. API receives request -> Validates -> Checks Credits -> Adds to Queue -> Returns 202.
  2. Worker picks job -> Calls Google Gemini API -> Updates DB -> Deducts Credits.
  3. Worker adds to `webhook-deliveries` queue.
- **Reliability**: Automatic retries (3x) with exponential backoff.
- **Dead Letter Queue**: Failed jobs moved here for manual inspection.

### 3.3 Translation Integration (Google Gemini API)
- **Service**: Google Gemini API (gemini-3-flash-preview).
- **Infrastructure**: Cloud-based neural translation (no GPU management needed).
- **Logic**: HTML-aware translation (preserves tags via placeholder system).
- **Token Counting**: Accurate billing based on input+output tokens.
- **Response Time**: Fast translation (~1-2s per request).

### 3.4 Billing & Payments
- **Gateway**: PayPal Subscriptions API.
- **Credit System**: 1 token ≈ 1 word.
- **Tiers**:
  - Starter: $9/mo (100k tokens)
  - Pro: $29/mo (500k tokens)
  - Enterprise: $99/mo (2M tokens)
- **Auto-refill**: Webhook listener for PayPal `BILLING.SUBSCRIPTION.RENEWED`.

### 3.5 Admin Dashboard
- **Tech**: React + Vite + TanStack Query + TailwindCSS.
- **Features**:
  - User management (suspend/activate).
  - API key revocation.
  - Usage analytics charts (Recharts).
  - Job monitoring (Bull Board integration).
  - System health status.

---

## 4. Infrastructure & Deployment

### 4.1 Docker Strategy
- **Multi-stage builds**: Reduce image size.
- **Services**:
  - `api`: Express server.
  - `worker`: Job processor.
  - `web`: React admin (served via Nginx).
- **Orchestration**: Docker Compose (Dev), Kubernetes (Prod).

### 4.2 CI/CD Pipeline (GitHub Actions)
1. **Lint & Test**: Run ESLint and Jest.
2. **Build**: Build Docker images.
3. **Push**: Push to container registry (GHCR/ECR).
4. **Deploy**: Update Kubernetes manifest / SSH to server.

### 4.3 Monitoring & Logging
- **Logs**: Winston (JSON format) -> ELK Stack / Datadog.
- **Metrics**: Prometheus endpoint (`/metrics`) for request rate, latency, error rate.
- **Alerts**: Slack notifications for critical errors (5xx spikes, payment failures).

---

## 5. Development Roadmap

### Phase 1: Core API & DB (Weeks 1-2)
- [x] Express setup + Prisma schema.
- [x] Auth middleware (API Key + JWT).
- [ ] Basic CRUD endpoints.
- [ ] Unit tests for auth.

### Phase 2: Queue & Translation Integration (Weeks 3-4)
- [ ] Redis + Bull setup.
- [ ] Google Gemini API client implementation.
- [ ] Job processor implementation.
- [ ] Translation integration tests.

### Phase 3: Billing & Webhooks (Weeks 5-6)
- [ ] PayPal integration.
- [ ] Credit ledger logic.
- [ ] Outgoing webhook retry system.
- [ ] End-to-end payment tests.

### Phase 4: Admin Panel (Weeks 7-8)
- [ ] React dashboard build.
- [ ] Analytics charts.
- [ ] User management UI.
- [ ] Admin auth integration.

### Phase 5: Hardening & Launch (Weeks 9-10)
- [ ] Rate limiting tuning.
- [ ] Security audit (penetration testing).
- [ ] Load testing (1000 concurrent jobs).
- [ ] Documentation (OpenAPI/Swagger).

---

## 6. API Specification (Preview)

### `POST /v1/jobs`
Submit a translation job.

**Request:**
```json
{
  "source_lang": "en",
  "target_lang": "es",
  "content": "<p>Hello world</p>",
  "tone": "neutral",
  "callback_url": "https://site.com/wp-json/mpz/v1/webhook"
}
```

**Response (202 Accepted):**
```json
{
  "job_id": "uuid-1234",
  "status": "queued",
  "estimated_tokens": 5
}
```

### `GET /v1/jobs/:id`
Check job status.

**Response:**
```json
{
  "id": "uuid-1234",
  "status": "completed",
  "translation": "<p>Hola mundo</p>",
  "tokens_used": 5,
  "cost": 0.000025
}
```

---

## 7. Success Metrics
- **Latency**: Sync requests < 2s (P95).
- **Throughput**: Support 10,000 jobs/hour.
- **Reliability**: 99.9% success rate for jobs.
- **Cost Efficiency**: Optimize Gemini API token usage.