# Backend API Implementation Plan

## Overview
**Objective:** Build a scalable, secure Node.js backend for the Translate Press Zone service.
**Tech Stack:** Node.js, Express, PostgreSQL, Prisma, Redis, Bull, Google Gemini API

---

## Phase 0: Licensing Microservice (Week 1)

### Task 0.1: Licensing Schema & Logic
**Required Skills:** `licensing-system`, `database-schema-design`
- [ ] Define `License`, `LicenseActivation`, and `PluginRelease` models in Prisma
- [ ] Create `LicenseService` for key generation, hashing, and validation
- [ ] Implement logic for domain limit enforcement (1 site, 5 sites, Unlimited)
- [ ] Configure Pricing Tiers: Starter ($299), Professional ($1,499), Enterprise ($4,999)

### Task 0.2: License API Endpoints
**Required Skills:** `licensing-system`, `api-endpoint-creation`
- [ ] Create POST `/v1/licenses/activate` (Validate key + domain, return token)
- [ ] Create POST `/v1/licenses/deactivate`
- [ ] Create GET `/v1/licenses/check` (Validation for plugin heartbeat)
- [ ] Create GET `/v1/updates/check` (Serve update package URL)

---

## Phase 1: Foundation & Security (Weeks 1-2)

### Task 1.1: Project Skeleton & Configuration
**Required Skills:** `api-endpoint-creation`, `deployment-dockerization`
- [ ] Initialize Node.js TypeScript project structure
- [ ] Configure ESLint, Prettier, and tsconfig.json
- [ ] Setup environment variables validation (dotenv + zod)
- [ ] Create Dockerfile and docker-compose.yml for dev environment

### Task 1.2: Database Architecture
**Required Skills:** `database-schema-design`
- [ ] Initialize Prisma with PostgreSQL connection
- [ ] Define `User` model (email, password_hash, role)
- [ ] Define `ApiKey` model (hashed_key, prefix, user_id)
- [ ] Define `Subscription` and `CreditTransaction` models
- [ ] Run initial migration and generate Prisma client

### Task 1.3: Authentication System
**Required Skills:** `authentication-security`, `database-schema-design`
- [ ] Implement JWT utility (sign, verify, refresh)
- [ ] Create `auth` middleware for Bearer token extraction
- [ ] Implement `login` and `register` endpoints
- [ ] Implement API Key generation and hashing logic
- [ ] Create `requireApiKey` middleware for public API access

---

## Phase 2: Core API Development (Weeks 3-4)

### Task 2.1: Translation Job Management
**Required Skills:** `api-endpoint-creation`, `database-schema-design`
- [ ] Define `TranslationJob` model in Prisma
- [ ] Create POST `/v1/jobs` endpoint with Zod validation
- [ ] Create GET `/v1/jobs/:id` endpoint for status polling
- [ ] Implement rate limiting middleware (Redis-backed)

### Task 2.2: Job Queue Implementation
**Required Skills:** `queue-management`
- [ ] Setup Redis connection for Bull queues
- [ ] Create `translation-jobs` queue configuration
- [ ] Implement job producer in the POST `/v1/jobs` handler
- [ ] Create basic worker process structure

---

## Phase 3: Translation Integration & Workers (Weeks 5-6)

### Task 3.1: Google Gemini API Integration
**Required Skills:** `ml-service-integration`, `queue-management`
- [ ] Implement `GeminiClient` class for Google Gemini API
- [ ] Create worker processor for translation jobs
- [ ] Implement token counting logic (input + output)
- [ ] Handle Gemini API errors and retries

### Task 3.2: Webhook Delivery System
**Required Skills:** `webhook-implementation`, `queue-management`
- [ ] Create `webhook-deliveries` queue
- [ ] Implement webhook worker with exponential backoff
- [ ] Add HMAC signature generation for outgoing webhooks
- [ ] Trigger webhook on job completion

---

## Phase 4: Business Logic & Billing (Weeks 7-8)

### Task 4.1: Credit System
**Required Skills:** `payment-integration`, `database-schema-design`
- [ ] Implement `CreditService` for atomic balance updates
- [ ] Enforce credit checks before job acceptance
- [ ] Deduct credits upon job completion

### Task 4.2: PayPal Integration
**Required Skills:** `payment-integration`, `webhook-implementation`
- [ ] Implement PayPal Subscriptions API client
- [ ] Create endpoint for PayPal webhook listener
- [ ] Handle `BILLING.SUBSCRIPTION.ACTIVATED` events
- [ ] Implement monthly credit refill logic

---

## Phase 5: Admin Dashboard (Weeks 9-10)

### Task 5.1: Admin API Endpoints
**Required Skills:** `api-endpoint-creation`, `authentication-security`
- [ ] Create GET `/v1/admin/stats` for system metrics
- [ ] Create User management endpoints (list, suspend)
- [ ] Implement role-based access control (RBAC) middleware

### Task 5.2: React Admin Panel
**Required Skills:** `admin-dashboard-react`
- [ ] Initialize Vite + React + TypeScript project
- [ ] Setup TanStack Query and Zustand store
- [ ] Implement Login page with JWT handling
- [ ] Create Dashboard overview with Recharts
- [ ] Build User management data grid

---

## Phase 6: Operations & Hardening (Weeks 11-12)

### Task 6.1: Logging & Monitoring
**Required Skills:** `error-handling-logging`
- [ ] Configure Winston logger with rotation
- [ ] Implement global error handling middleware
- [ ] Create `AuditLog` model and tracking middleware

### Task 6.2: Production Deployment
**Required Skills:** `deployment-dockerization`
- [ ] Optimize Dockerfile (multi-stage build)
- [ ] Create Kubernetes manifests (Deployment, Service, Ingress)
- [ ] Setup GitHub Actions CI/CD pipeline