encoach_frontend_new_v3/docs/ARCHITECTURE.md

EnCoach Platform -- Architecture & Connectivity Document

Overview

EnCoach is an IELTS preparation and English proficiency testing platform composed of four repositories that work together as a distributed system. The platform supports exam taking, AI-powered grading, training content, multi-tenant entity management, payments, and a public-facing marketing website.

---

Repositories at a Glance

• ielts-ui -- Full-stack Next.js 14 app. The main platform for students, teachers, admins, and corporate users. Serves both the browser UI and internal API routes.
• ielts-be -- Python/FastAPI backend. Handles AI/ML workloads: exam generation, grading (writing/speaking), audio transcription, TTS, and training content.
• encoachcms -- Strapi v4 headless CMS. Manages bilingual (EN/AR) marketing content for the landing page.
• encoach-landing-page -- Next.js 13 marketing website. Consumes CMS content and links users into the main platform.

---

System Architecture Diagram

graph TB
  subgraph publicFacing ["Public-Facing Layer"]
    LP["encoach-landing-page<br/>(Next.js 13)"]
    CMS["encoachcms<br/>(Strapi v4)"]
  end

  subgraph platformCore ["Platform Core"]
    UI["ielts-ui<br/>(Next.js 14 + API Routes)"]
    BE["ielts-be<br/>(FastAPI / Python)"]
  end

  subgraph dataStores ["Data Stores"]
    MongoDB["MongoDB"]
    MySQL["MySQL<br/>(CMS)"]
    FirebaseAuth["Firebase Auth"]
    FirebaseStorage["Firebase Storage"]
    GCS["Google Cloud Storage<br/>(CMS uploads)"]
  end

  subgraph externalServices ["External Services"]
    OpenAI["OpenAI GPT-4o"]
    Whisper["OpenAI Whisper<br/>(local)"]
    Polly["AWS Polly<br/>(TTS)"]
    ELAI["ELAI<br/>(AI Video)"]
    GPTZero["GPTZero<br/>(AI Detection)"]
    Stripe["Stripe"]
    PayPal["PayPal"]
    Paymob["Paymob"]
  end

  LP -->|"REST + Bearer token"| CMS
  LP -->|"GET /api/packages, POST /api/tickets"| UI
  LP -->|"Links to platform.encoach.com"| UI

  CMS --> MySQL
  CMS --> GCS

  UI --> MongoDB
  UI --> FirebaseAuth
  UI -->|"Proxy: Bearer JWT"| BE

  BE --> MongoDB
  BE --> FirebaseAuth
  BE --> FirebaseStorage
  BE --> OpenAI
  BE --> Whisper
  BE --> Polly
  BE --> ELAI
  BE --> GPTZero

  UI --> Stripe
  UI --> PayPal
  UI --> Paymob
  LP --> Stripe

---

1. ielts-ui (Main Platform)

Tech: Next.js 14, React 18, TypeScript, Tailwind CSS + DaisyUI, Zustand, SWR, iron-session, Firebase Auth, MongoDB (direct)

Role: The central application. Serves the browser UI and acts as a BFF (Backend-for-Frontend) via Next.js API routes. It directly queries MongoDB for user/entity/group data and proxies AI-related requests to ielts-be.

Key Modules

Module	Description
Auth	Firebase email/password auth + iron-session cookies. SSR-protected via withIronSessionSsr.
Dashboards	Role-based: student, teacher, admin, corporate, mastercorporate, developer, agent.
Exams	Taking exams (Reading, Listening, Writing, Speaking, Level). Zustand store tracks session, progress, solutions.
Exam Editor	Create/edit exams with dedicated components under src/components/ExamEditor/.
Training	Training content consumed from ielts-be.
Grading	Writing and speaking grading proxied to ielts-be as background tasks; UI polls for results.
Entities	Multi-tenant entity management (schools, organizations).
Classrooms	Classroom and group management for teachers.
Assignments	Assign exams to students with deadlines.
Stats	Performance statistics and PDF report generation (via @react-pdf/renderer).
Payments	Stripe, PayPal, Paymob webhook handlers in API routes.
Tickets	Support ticket system.
User Mgmt	Bulk import, permissions, role-based access.

How it Connects to ielts-be

API routes in src/pages/api/ proxy to BACKEND_URL with Authorization: Bearer ${BACKEND_JWT}:

UI API Route	Backend Endpoint
/api/evaluate/writing	BACKEND_URL/grade/writing/{task}
/api/evaluate/speaking	BACKEND_URL/grade/speaking/{task}
/api/transcribe	BACKEND_URL/listening/transcribe
/api/training	BACKEND_URL/training/
/api/exam/upload	BACKEND_URL/{endpoint}
/api/exam/media/*	BACKEND_URL/{endpoint}/media
/api/exam/generate/*	BACKEND_URL/{endpoint}
/api/exam/avatars	BACKEND_URL/speaking/avatars
/api/exam/[module]/import	BACKEND_URL/{module}/import
/api/stats/[id]/[export]/pdf	BACKEND_URL/grade/summary
/api/batch_users	BACKEND_URL/user/import

How it Connects to the Landing Page

Exposes public-ish API routes consumed by the landing page:

• GET /api/packages -- subscription packages (CORS-enabled)
• POST /api/tickets -- contact form submissions (CORS-enabled)
• GET /api/users/agents -- list sales agents (CORS-enabled)

---

2. ielts-be (AI/ML Backend)

Tech: Python 3.11, FastAPI, Motor (async MongoDB), Poetry, dependency-injector, OpenAI, Whisper, AWS Polly, ELAI, FAISS

Role: Handles all AI/ML-intensive operations -- exam content generation, grading, transcription, text-to-speech, AI video, and training recommendations. Runs as a standalone service on port 8000.

Architecture Layers

API Routes --> Controllers --> Services --> Repositories
                                  |
                          Third-Party Services
                     (OpenAI, Whisper, Polly, ELAI, GPTZero)

Wired together via dependency-injector.

Key Capabilities

Capability	Implementation
Writing Grading	GPT-4o evaluates against IELTS rubric (Task Achievement, Coherence, Lexical Resource, Grammar). GPTZero checks for AI-generated text. Runs as background task; results stored in evaluation collection.
Speaking Grading	Whisper transcribes audio, then GPT grades (Fluency, Lexical, Grammar, Pronunciation). Parts 1/2/3 supported.
Exam Generation	GPT generates reading passages, listening dialogs, writing prompts, speaking tasks, and level-test exercises.
Audio (TTS)	AWS Polly synthesizes MP3 for listening sections.
Video	ELAI generates AI avatar videos for speaking prompts.
Transcription	Whisper (local model) for speech-to-text.
Training	FAISS + sentence-transformers for semantic search over tips; GPT for personalized recommendations.
Short Answer Grading	GPT-4o for reading/listening fill-in-the-blank answers.

Authentication

All endpoints (except /api/healthcheck) require a Bearer JWT token validated with JWT_SECRET_KEY (HS256). The ielts-ui sends this as BACKEND_JWT.

---

3. encoachcms (Content Management)

Tech: Strapi v4.21, Node.js 18, MySQL (prod) / SQLite (dev), Google Cloud Storage for uploads

Role: Headless CMS for managing the marketing website content. Editors create/update bilingual (EN/AR) content via the Strapi admin panel at /admin.

Content Types (all Single Types)

home, about, services, contact, footer, nav-bar, history, price, terms-and-conditions, privacy-policy, country-managers-contact

How it Connects

• Exposes REST API at STRAPI_URL/api/{content-type}/?populate=deep&locale={en|ar}
• Authenticated via API token (STRAPI_TOKEN)
• Only consumed by encoach-landing-page -- neither ielts-ui nor ielts-be use it

Plugins

• strapi-plugin-populate-deep -- deep relation population
• strapi-plugin-import-export-entries -- content import/export
• strapi-plugin-publisher -- scheduled publishing
• @strapi/plugin-i18n -- internationalization
• @strapi/plugin-documentation -- OpenAPI docs

---

4. encoach-landing-page (Marketing Website)

Tech: Next.js 13 (App Router), TypeScript, Tailwind CSS + DaisyUI, Stripe

Role: Public marketing website at encoach.com. Bilingual (EN at /, AR at /ar/). Fetches content from the CMS and links users into the main platform.

Pages

/ (Home), /about, /services, /price, /history, /contact, /terms, /privacy-policy, /contacts/[country], /success -- all mirrored under /ar/ for Arabic.

How it Connects

Target	Connection
encoachcms	getData() fetches STRAPI_URL/api/{page}/?populate=deep&locale={locale} with Bearer token
ielts-ui	GET /api/packages for pricing, POST /api/tickets for contact form, GET /api/users/agents for sales agents
Stripe	Checkout flow; /api/success route validates session and POSTs to WEBHOOK_URL
Platform links	Buttons link to platform.encoach.com/register, platform.encoach.com/official-exam

---

Data Flow Diagrams

Authentication Flow

sequenceDiagram
    participant Browser
    participant UI as ielts-ui
    participant Firebase as Firebase Auth
    participant Mongo as MongoDB

    Browser->>UI: POST /api/login (email, password)
    UI->>Firebase: signInWithEmailAndPassword
    Firebase-->>UI: Firebase UID + token
    UI->>Mongo: Find user by Firebase UID
    Mongo-->>UI: User document
    UI->>UI: Save to iron-session cookie
    UI-->>Browser: Set-Cookie (eCrop/ielts)
    Browser->>UI: Subsequent requests with cookie
    UI->>UI: withIronSessionSsr validates cookie

Exam Grading Flow (Writing)

sequenceDiagram
    participant Student
    participant UI as ielts-ui API Route
    participant BE as ielts-be
    participant GPT as OpenAI GPT-4o
    participant GPTZero as GPTZero
    participant Mongo as MongoDB

    Student->>UI: Submit writing answer
    UI->>BE: POST /api/exam/grade/writing/{task}
    BE->>BE: Start background task
    BE-->>UI: 200 OK (accepted)
    UI-->>Student: "Grading in progress"

    par Parallel Grading
        BE->>GPT: Evaluate against IELTS rubric
        GPT-->>BE: Scores + feedback
    and AI Detection
        BE->>GPTZero: Check for AI content
        GPTZero-->>BE: AI probability
    end

    BE->>Mongo: Save evaluation result
    Student->>UI: Poll for result
    UI->>Mongo: Query evaluation
    Mongo-->>UI: Grading result
    UI-->>Student: Display scores + feedback

Landing Page Content Flow

sequenceDiagram
    participant Visitor
    participant LP as encoach-landing-page
    participant CMS as encoachcms (Strapi)
    participant Platform as ielts-ui

    Visitor->>LP: Visit encoach.com
    LP->>CMS: GET /api/home/?populate=deep&locale=en
    CMS-->>LP: Home content (JSON)
    LP-->>Visitor: Rendered page

    Visitor->>LP: View pricing
    LP->>CMS: GET /api/price/?populate=deep&locale=en
    LP->>Platform: GET /api/packages
    Platform-->>LP: Package list
    LP-->>Visitor: Pricing page with packages

    Visitor->>LP: Submit contact form
    LP->>Platform: POST /api/tickets
    Platform-->>LP: Ticket created

---

Shared Infrastructure

Resource	Used By	Details
MongoDB	ielts-ui, ielts-be	Same database (MONGODB_URI / MONGODB_DB). UI reads users, groups, stats directly. BE reads/writes evaluations, training.
Firebase Auth	ielts-ui, ielts-be	Shared Firebase project. UI handles login/signup; BE imports users.
Firebase Storage	ielts-be	Stores exam media (audio, images).
Google Cloud Storage	encoachcms	CMS file uploads (images, media).

---

Deployment Topology

Service	Port	URL (Production)
ielts-ui	3000	platform.encoach.com
ielts-be	8000	Internal (proxied by ielts-ui)
encoachcms	1337	Internal (consumed by landing page)
encoach-landing-page	3000	encoach.com

Both Next.js apps use output: "standalone" and have Dockerfiles. The BE is not directly exposed to the internet -- it sits behind ielts-ui's API route proxy layer.

---

User Roles

Role	Access
student	Take exams, view stats, training, assignments
teacher	Manage classrooms, assignments, view student performance
admin	Full platform management, user management, entities
corporate	Corporate dashboard, bulk operations
mastercorporate	Multi-entity corporate management
developer	Developer dashboard, system tools
agent	Sales agent, visible on landing page

---

Key Environment Variables (Cross-Service)

Variable	Service	Purpose
MONGODB_URI / MONGODB_DB	ielts-ui, ielts-be	Shared MongoDB
BACKEND_URL	ielts-ui	URL of ielts-be
BACKEND_JWT / JWT_SECRET_KEY	ielts-ui / ielts-be	Shared JWT secret for service-to-service auth
FIREBASE_*	ielts-ui, ielts-be	Shared Firebase project credentials
STRAPI_URL / STRAPI_TOKEN	encoach-landing-page	CMS connection
STRIPE_KEY / STRIPE_SECRET	ielts-ui, encoach-landing-page	Payment processing
OPENAI_API_KEY	ielts-be	AI grading and generation
AWS_ACCESS_KEY_ID/SECRET	ielts-be	AWS Polly TTS