avaaz/docs/plan.md

# Avaaz Implementation Plan

This implementation plan translates the Product Requirements (`docs/PRD.md`), product description (`README.md`), and system architecture (`docs/architecture.md`) into concrete, phased engineering work for a production-grade Avaaz deployment.

The goal is to deliver an end-to-end, voice-first AI speaking coach that supports learners from A1–B2, with B2 oral exam readiness as the primary outcome.

---

## 1. Guiding Principles

- **B2 exam readiness first, A1–B2 capable:** Design features and data models so that they support A1–B2 learners, but prioritize workflows that move learners toward B2 oral exam success.
- **Voice-first, text-strong:** Optimize for real-time speech-to-speech interactions, with robust transcripts and text UX as first-class companions.
- **Single source of truth:** Keep curriculum, lessons, transcripts, and analytics centralized in PostgreSQL + pgvector; no separate vector store.
- **Continuous sessions:** All conversations run within persistent sessions (`/sessions/default`), preserving state across reconnects.
- **Infrastructure parity:** Development Docker stack mirrors production VPS stacks (infra/app), as described in `docs/architecture.md`.
- **Security and privacy:** Apply strong auth, least-privilege access, safe logging, and clear retention policies for voice/transcript data.

---

## 2. High-Level Phasing

### Phase 1 – Foundation (M0–M2)

- Set up core infrastructure (Dockerized backend, frontend, LiveKit, Postgres+pgvector, Caddy).
- Implement authentication, user model, and basic session handling.
- Implement minimal voice conversation loop (user ↔ AI tutor) with basic transcripts.
- Define initial CEFR-aware curriculum data model and seed a small set of lessons.

### Phase 2 – Learning Experience & Analytics (M3–M4)

- Implement full A1–B2 curriculum representation, scenarios, and level-aware adaptive tutoring.
- Add progress dashboard, gamification basics, and post-session summaries.
- Implement AI-assisted lesson authoring and learner-upload-based lessons.
- Introduce mock exam templates (A1–A2, A2–B1, B1–B2) and B2-focused exam reports.

### Phase 3 – Scale, Reliability & Monetization (M5–M6)

- Harden infrastructure (observability, health checks, admin dashboards).
- Add subscription plans and Stripe integration.
- Optimize performance (latency, concurrency), tune analytics pipelines, and finalize launch-readiness tasks.

---

## 3. Backend Workstream (FastAPI + LiveKit + LLMs)

### 3.1 Core Service Setup

**Goals**

- Production-ready FastAPI service with auth, sessions, and integrations.

**Tasks**

- Use the existing backend layout under `app/backend` as the foundation:
  - `app/backend/main.py` – app factory and router wiring.
  - `app/backend/core/config.py` – Pydantic-settings for core configuration, DB_URL, LLM keys, LiveKit, Stripe, etc.
  - `app/backend/core/database.py` – database/session utilities; extend to add SQLAlchemy, pgvector, and Alembic integration.
  - `app/backend/api/v1/router.py` – versioned API router aggregator; include routers from feature and operation modules (existing `features.auth`, `operations.health`, plus future `lessons`, `chat`, `documents`).
  - `app/backend/features/*` and `app/backend/operations/*` – domain logic and HTTP routers (e.g., auth, lessons, chat, payments, document upload, health).
- Implement base middleware (CORS, logging, request ID, error handling).
- Ensure `/health`, `/health/live`, and `/health/ready` endpoints are wired and return basic dependency checks (DB connectivity, LiveKit reachability, LLM connectivity where safe).

**Deliverables**

- Running FastAPI service in Docker with `/health` OK and OpenAPI docs available.

### 3.2 Data Model & Persistence

**Goals**

- Support A1–B2 curriculum, lessons, sessions, transcripts, and analytics in PostgreSQL + pgvector.

**Tasks**

- Design and implement SQLAlchemy models:
  - `User` – profile, locale, target level, subscription plan, preferences.
  - `CurriculumObjective` – per level (A1–B2), skill (reception, production, interaction, mediation), descriptor text.
  - `Lesson` – CEFR level, objectives, type (lesson, scenario, exam part), metadata (topic, context).
  - `Scenario` / `ScenarioStep` – structured oral tasks (self-presentation, picture description, opinion exchange, arguing a statement) with configuration for timing and mode (individual/pair).
  - `Session` – persistent conversational session per user (mode, state, summary, last_activity_at).
  - `Turn` – individual utterances with role (user/AI), timestamps, raw transcript, audio reference, CEFR difficulty metadata.
  - `ExamTemplate` / `ExamPart` – A1–A2, A2–B1, B1–B2 templates with timing, task types, scoring dimensions.
  - `ExamAttempt` / `ExamScore` – attempt metadata, estimated CEFR level, component scores.
  - `UploadDocument` / `DocumentChunk` – files and parsed chunks with `vector` embeddings (stored alongside or extending the existing backend package under `app/backend`).
  - `ProgressSnapshot` – aggregate metrics for dashboards (per user and optionally per program).
  - `Subscription` / `PaymentEvent` – billing state and usage limits.
- Add related Alembic migrations; verify they run cleanly on dev DB.

**Deliverables**

- Migrations and models aligned with PRD feature set and architecture.

### 3.3 Authentication & User Management

**Goals**

- Secure user auth using FastAPI Users (or equivalent) with JWT and refresh tokens.

**Tasks**

- Configure FastAPI Users:
  - Email/password registration, login, password reset, email verification.
  - Role support (learner, instructor, admin) for curriculum authoring and admin dashboards.
- Integrate auth into routes (`dependencies.py` with `current_user`).
- Implement `users` endpoints for profile (target CEFR level, locale) and preferences (greeting verbosity, data retention preferences).

**Deliverables**

- Auth flows working in backend and callable from Postman / curl.

### 3.4 Session Management & Transcripts

**Goals**

- Provide continuous session behavior with persistent history, as described in `docs/architecture.md` and PRD.

**Tasks**

- Implement `GET /sessions/default`:
  - Create or fetch `Session` for current user.
  - Load summary, current lesson state, and progress context.
- Implement `POST /sessions/default/token`:
  - Generate short-lived LiveKit token with room identity tied to the session.
- Integrate with LiveKit Agent:
  - Implement an LLM integration module (for example under `app/backend/features/llm.py` or similar) that configures the realtime session using historical summary, current goals, and mode (lesson/mock exam/free).
- Implement transcript persistence:
  - Receive partial/final transcripts from LiveKit/agent.
  - Append `Turn` records and maintain rolling summaries for context.
  - Respect retention settings.
- Implement post-session summarization endpoint / background job:
  - Generate per-session summary, strengths/weaknesses, recommended next steps.

**Deliverables**

- API and background flows that maintain continuous conversational context per user.

### 3.5 Curriculum & Lesson APIs

**Goals**

- Expose CEFR-aligned curriculum and lesson content to frontend and agent.

**Tasks**

- Implement `lessons` router:
  - List lessons by level, topic, recommended next steps.
  - Fetch details for a specific lesson, including objectives and scenario steps.
  - Mark lesson progress and completion; update `ProgressSnapshot`.
- Implement endpoints for curriculum objectives and mapping to lessons.
- Implement endpoints to retrieve scenario templates for mock exams and regular lessons.

**Deliverables**

- Stable JSON API for curriculum and lessons, used by frontend and agent system prompts.

### 3.6 AI-Assisted Authoring & User Uploads

**Goals**

- Support instructor-designed and learner-generated lessons from uploaded materials.

**Tasks**

- Implement `documents` router:
  - File upload endpoints for documents and images (instructor and learner scopes).
  - Trigger document processing pipeline (Docling or similar) to parse text and structure.
  - Chunk documents and store embeddings in `DocumentChunk` using pgvector.
- Implement instructor authoring endpoints:
  - Create/update/delete lessons referencing uploaded documents/images.
  - AI-assisted suggestion endpoint that uses LLM to propose lesson structure, prompts, and exam-style tasks conditioned on level and objectives.
- Implement learner upload endpoints:
  - User-specific upload and lesson creation (on-the-fly lessons).
  - Link created “ad-hoc” lessons to sessions so the tutor can reference them during practice.

**Deliverables**

- Endpoints supporting both admin/instructor authoring and user-driven contextual lessons.

### 3.7 Mock Exam Engine & Scoring

**Goals**

- Implement configurable mock oral exam flows for A1–A2, A2–B1, and B1–B2, with B2 focus.

**Tasks**

- Implement exam orchestration service:
  - Given an `ExamTemplate`, manage progression through `ExamPart`s (including warm-up, individual tasks, pair tasks).
  - Enforce timing and mode flags to drive agent prompts.
- Integrate scoring:
  - Use LLM to derive component scores (fluency, pronunciation, grammar, vocabulary, coherence) from transcripts.
  - Map to estimated CEFR band and store in `ExamScore`.
- Expose endpoints:
  - Start exam, fetch exam status, retrieve past exam results.

**Deliverables**

- End-to-end exam session that runs via the same LiveKit + agent infrastructure and stores exam results.

### 3.8 Analytics & Reporting

**Goals**

- Provide learner-level dashboards and program-level reporting.

**Tasks**

- Implement periodic aggregation (cron/async tasks) populating `ProgressSnapshot`.
- Implement analytics endpoints:
  - Learner metrics (minutes spoken, session counts, trends per skill).
  - Program-level metrics (for instructors/coordinators) with appropriate role-based access.
- Ensure privacy controls (anonymized or pseudonymized data where required).

**Deliverables**

- Backend API supporting progress dashboards and reports as per PRD.

---

## 4. Frontend Workstream (Next.js + LiveKit)

### 4.1 Foundation & Layout

**Goals**

- Production-ready Next.js PWA front-end that matches Avaaz branding and supports auth, routing, and basic pages.

**Tasks**

- Initialize Next.js app (per `README.md`):
  - Configure `next.config.js`, TypeScript, ESLint, PWA manifest, and global styles.
  - Implement `app/layout.tsx` with theme, localization provider, and navigation.
  - Implement `app/page.tsx` landing page aligned with product positioning (A1–B2, B2 focus).
- Implement auth pages (login, register, email verification, forgot password).

**Deliverables**

- Frontend skeleton running under Docker, reachable via Caddy in dev stack.

### 4.2 Chat & Voice Experience

**Goals**

- Voice-first conversational UI integrated with LiveKit and backend sessions.

**Tasks**

- Build `ChatInterface.tsx`:
  - Microphone controls, connection status, basic waveform/level visualization.
  - Rendering of AI and user turns with text and visual aids (images, tables) as provided by backend/agent.
  - Error states for mic and network issues; text-only fallback UI.
- Integrate with backend session APIs:
  - On login, call `GET /sessions/default`, then `POST /sessions/default/token`.
  - Connect to LiveKit using the token; handle reconnection logic.
- Display contextual greeting and summary on session start using data returned from `sessions` API.

**Deliverables**

- Usable chat interface capable of sustaining real-time conversation with the AI tutor.

### 4.3 Curriculum & Lesson UX

**Goals**

- Allow learners to browse curriculum, start lessons, and view progress.

**Tasks**

- Implement curriculum overview page:
  - Display modules and lessons grouped by CEFR levels (A1–B2).
  - Indicate completion and recommended next lessons.
- Implement lesson detail page:
  - Show lesson goals, target level, estimated time, and exam-related tags.
  - Start lesson → opens chat view in appropriate mode with lesson context.
- Integrate progress indicators (streaks, minutes, CEFR band) into dashboard.

**Deliverables**

- Navigation and views covering core learning flows described in PRD.

### 4.4 Mock Exam UX

**Goals**

- Implement exam-specific UX consistent with oral exams and PRD.

**Tasks**

- Build exam selection page:
  - Allow user to choose exam level (A1–A2, A2–B1, B1–B2/B2-mock).
- In-session exam UI:
  - Show current exam part, timer, and appropriate instructions.
  - Indicate whether current part is scored or warm-up.
- Results page:
  - Show estimated CEFR level, component scores, and textual feedback.
  - Provide links to detailed transcripts, audio, and recommended follow-up lessons.

**Deliverables**

- End-to-end exam flow from selection to results.

### 4.5 AI-Assisted Authoring & Upload UX

**Goals**

- Provide UIs for instructors and learners to upload content and create lessons.

**Tasks**

- Instructor interface:
  - Lesson builder UI with level, objectives, exam part, and document selection.
  - “Generate with AI” action to fetch suggested prompts/structure; edit-in-place and publish.
- Learner interface:
  - Simple upload flow (document/image) to create ad-hoc practice.
  - Quick-start buttons to jump from uploaded content to a tailored lesson in the chat interface.

**Deliverables**

- Authoring tools that map onto backend authoring APIs.

### 4.6 Analytics & Admin Health Dashboard

**Goals**

- Provide admin and instructor dashboards for system health and learner analytics.

**Tasks**

- Learner dashboard:
  - Visualize key metrics and streaks, integrated with backend analytics.
- Instructor/program dashboard:
  - Aggregate usage and progress metrics for groups.
- Admin health dashboard:
  - Surface backend `/health` status, LiveKit status, DB health indicators, and LLM connectivity signals.

**Deliverables**

- Dashboards that satisfy PRD’s analytics and health visibility requirements.

---

## 5. Real-Time & Media Workstream (LiveKit + Agents)

### 5.1 LiveKit Server & Config

**Tasks**

- Use the existing `livekit` service in `app/docker-compose.yml` as the basis, keeping signaling on port 7880 and the WebRTC media port range configurable via environment variables (currently defaulting to 60000–60100) and attached to the shared `proxy` network used by Caddy.
- Ensure secure API keys and appropriate room/track settings for voice-only sessions.
- Configure UDP ports and signaling endpoints (`rtc.avaaz.ai` → Caddy → `livekit:7880`) as described in `docs/architecture.md` and `infra/Caddyfile`.

### 5.2 Client Integration

**Tasks**

- Wire frontend to LiveKit:
  - Use `@livekit/client` to join rooms using tokens from backend.
  - Handle reconnection and session resumption.
- Integrate with backend session and agent orchestration.

### 5.3 Agent Integration with Realtime LLMs

**Tasks**

- Implement LiveKit Agent that:
  - Connects to OpenAI Realtime or Gemini Live according to configuration.
  - Streams user audio and receives streamed AI audio and partial transcripts.
  - Forwards transcripts and metadata to backend for persistence.
- Implement prompt templates for:
  - Regular lessons, mock exams, free conversation.
  - CEFR-level adaptation and exam-specific tasks.

**Deliverables**

- Stable real-time pipeline from user microphone to LLM and back, integrated with backend logic.

---

## 6. Infrastructure & DevOps Workstream

### 6.1 Docker & Compose

**Tasks**

- Define and refine:
  - `infra/docker-compose.yml` – infra stack (Caddy, Gitea, Gitea runner).
  - `app/docker-compose.yml` – app stack (frontend, backend, LiveKit, Postgres+pgvector).
- Configure volumes and networks (`proxy` network for routing via Caddy).

### 6.2 CI & CD (Gitea + Actions)

**Tasks**

- CI:
  - Extend `.gitea/workflows/ci.yml` to run linting, type-checking, and tests for backend and frontend once those projects are scaffolded under `app/backend` and `app/frontend`.
  - Add build verification for any Docker images produced for the app stack.
- CD:
  - Use `.gitea/workflows/cd.yml` as the tag-based deploy workflow, following the deployment approach in `docs/architecture.md`.
  - Deploy tags `v*` only if they are on `main`.
  - Use `/health` and key endpoints for readiness checks; roll back on failures.

### 6.3 Observability & Monitoring

**Tasks**

- Centralize logs and metrics for backend, frontend, LiveKit, and Postgres.
- Configure alerting for:
  - Application errors.
  - Latency and uptime SLOs for voice and API endpoints.
  - Resource usage (CPU, memory, DB connections).

---

## 7. Quality, Security, and Compliance

### 7.1 Testing Strategy

**Tasks**

- Backend:
  - Unit tests for core logic modules (e.g., health checks, config, LLM/document/payment integration) and any data models.
  - Integration tests for auth, sessions, and lessons using httpx + pytest.
- Frontend:
  - Component tests for core UI (chat, curriculum, dashboards).
  - E2E flows for login, start lesson, start exam, and view progress.
- Voice stack:
  - Automated sanity checks for LiveKit connectivity and audio round-trip.

### 7.2 Security & Privacy

**Tasks**

- Apply OWASP-aligned input validation and output encoding.
- Enforce HTTPS everywhere via Caddy; HSTS and secure cookies where applicable.
- Implement appropriate retention and deletion policies for audio and transcripts.
- Document data handling for learners and institutions (for future legal review).

---

## 8. Rollout Plan

### 8.1 Internal Alpha

- Run app stack locally for core team.
- Validate foundational flows: auth, voice session, basic lesson, transcripts.

### 8.2 Closed Beta

- Onboard a small cohort of A2–B2 learners and one or two programs.
- Focus on curriculum fit, tutor behavior, and exam simulation realism.
- Collect data to refine prompt templates, lesson design, and dashboard UX.

### 8.3 Public Launch

- Enable subscription plans and payment.
- Turn on production monitoring and on-call processes.
- Iterate on performance, reliability, and content quality based on real usage.