# rifatjahanazad-bd/ai-english-coach architecture

> Architecture diagram of the GitHub repository rifatjahanazad-bd/ai-english-coach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rifatjahanazad-bd/ai-english-coach
- Repository: https://github.com/rifatjahanazad-bd/ai-english-coach

## Overview

AI English Coach is a browser-based English-learning SPA backed by FastAPI and SQLite. Learners navigate from the dashboard into tutoring, CEFR practice, speaking assessment, meme learning, goals, and scoring; the backend routes requests to the relevant domain services and persistence. The README also describes Fast Phrases and Firestore live sync, but their implementing files are not present in the supplied tree, so those capabilities are represented only at the supported directory or external-service level. Relationships use README documentation and indexed source references; unsampled implementations limit detail.

Main entry points: [`backend/api/app.py`](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/app.py) (FastAPI Application), [`UI/js/api.js`](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/api.js) (API Client), [`backend/database/db.py`](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/database/db.py) (SQLite Database), [`UI/js/router.js`](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/router.js) (Client Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Client"]
  node_spa["SPA Shell<br/>[app.js]"]
  node_router["Client Router<br/>[router.js]"]
  node_api_client["API Client<br/>[api.js]"]
end

subgraph group_learning["Learning Experiences"]
  node_dashboard["Dashboard and Goals<br/>[dashboard.js]"]
  node_chat_ui["Chat Tutor<br/>[chat.js]"]
  node_practice_ui["Practice Arena<br/>[modulepractice.js]"]
  node_practice_tracks["CEFR Track Curricula"]
  node_speaking_ui["Speaking Simulator<br/>[memescreen.js]"]
  node_meme_ui["Meme Learning<br/>[memescreen.js]"]
  node_fast_phrases["Fast Phrases Game"]
end

subgraph group_api["API Services"]
  node_app_factory["FastAPI Application<br/>[app.py]"]
  node_api_config["API Configuration<br/>[config.py]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
  node_auth_routes["Authentication Routes<br/>[auth.py]"]
  node_chat_routes["Chat Routes<br/>[chat.py]"]
  node_goal_routes["Goal Routes<br/>[goals.py]"]
  node_module_routes["Module Routes<br/>[modules.py]"]
  node_speaking_routes["Speaking Routes<br/>[speaking.py]"]
  node_scoring_routes["Scoring Routes<br/>[scoring.py]"]
  node_meme_routes["Meme Routes<br/>[memes.py]"]
  node_system_routes["System Routes<br/>[system.py]"]
end

subgraph group_engines["AI and Processing"]
  node_chatbot["Tutor Engine<br/>[chatbot.py]"]
  node_prompt_loader["Prompt Loader<br/>[prompt_loader.py]"]
  node_audio_transcription["Audio Transcription<br/>[audio_to_txt.py]"]
  node_speaking_evaluator["Speaking Evaluator"]
  node_meme_generator["Meme Generator<br/>[meme_generator.py]"]
  node_meme_validator["Image Validator<br/>[meme_validator.py]"]
  node_meme_crop["Image Cropper<br/>[meme_crop.py]"]
  node_behavior_scoring["Behavior Scoring"]
end

subgraph group_state["Persistence and Sync"]
  node_sqlite[("SQLite Database<br/>[db.py]")]
  node_firestore[("Firestore")]
  node_firebase_auth["Firebase Auth"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_spa
node_spa -->|"routes through"| node_router
node_router -->|"selects view"| node_dashboard
node_router -->|"opens practice"| node_practice_ui
node_router -->|"opens test"| node_speaking_ui
node_router -->|"opens game"| node_fast_phrases
node_practice_ui -.->|"loads drills"| node_practice_tracks
node_chat_ui -.->|"requests chat"| node_api_client
node_dashboard -.->|"requests goals"| node_api_client
node_practice_ui -.->|"requests modules"| node_api_client
node_speaking_ui -.->|"submits audio"| node_api_client
node_meme_ui -.->|"requests memes"| node_api_client
node_api_client -->|"calls API"| node_app_factory
node_app_factory -->|"loads settings"| node_api_config
node_app_factory -->|"registers routes"| node_chat_routes
node_app_factory -->|"registers routes"| node_module_routes
node_app_factory -->|"registers routes"| node_speaking_routes
node_app_factory -->|"registers routes"| node_meme_routes
node_app_factory -->|"registers routes"| node_auth_routes
node_app_factory -->|"registers routes"| node_goal_routes
node_app_factory -->|"registers routes"| node_scoring_routes
node_app_factory -->|"registers routes"| node_system_routes
node_auth_routes -->|"validates with"| node_schemas
node_auth_routes -->|"reads and writes"| node_sqlite
node_module_routes -->|"loads curriculum"| node_sqlite
node_chat_routes -.->|"dispatches to"| node_chatbot
node_chatbot -->|"loads prompts"| node_prompt_loader
node_chatbot -->|"stores history"| node_sqlite
node_goal_routes -.->|"reads and writes"| node_sqlite
node_speaking_routes -->|"evaluates speech"| node_speaking_evaluator
node_speaking_routes -->|"verifies audio"| node_audio_transcription
node_speaking_evaluator -->|"transcribes audio"| node_audio_transcription
node_speaking_evaluator -->|"loads prompts"| node_prompt_loader
node_meme_routes -->|"generates memes"| node_meme_generator
node_meme_routes -->|"validates images"| node_meme_validator
node_meme_routes -->|"crops images"| node_meme_crop
node_meme_routes -->|"tracks quotas"| node_sqlite
node_meme_generator -->|"checks output"| node_meme_validator
node_meme_generator -->|"crops output"| node_meme_crop
node_scoring_routes -->|"evaluates events"| node_behavior_scoring
node_behavior_scoring -->|"loads and saves"| node_sqlite
node_learner -.->|"signs in"| node_firebase_auth
node_firebase_auth -.->|"authenticates"| node_firestore
node_firestore -.->|"syncs live state"| node_spa

click node_spa "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/app.js"
click node_router "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/router.js"
click node_api_client "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/api.js"
click node_dashboard "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/dashboard.js"
click node_chat_ui "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/chat.js"
click node_practice_ui "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/practice/modulepractice.js"
click node_practice_tracks "https://github.com/rifatjahanazad-bd/ai-english-coach/tree/main/UI/js/practice"
click node_speaking_ui "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/memescreen.js"
click node_meme_ui "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/memescreen.js"
click node_fast_phrases "https://github.com/rifatjahanazad-bd/ai-english-coach/tree/main/UI/js"
click node_app_factory "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/app.py"
click node_api_config "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/config.py"
click node_schemas "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/models/schemas.py"
click node_auth_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/auth.py"
click node_chat_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/chat.py"
click node_goal_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/goals.py"
click node_module_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/modules.py"
click node_speaking_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/speaking.py"
click node_scoring_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/scoring.py"
click node_meme_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/memes.py"
click node_system_routes "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/system.py"
click node_chatbot "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/chatbot.py"
click node_prompt_loader "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/prompt_loader.py"
click node_audio_transcription "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/audio_to_txt.py"
click node_speaking_evaluator "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/mp3_txt_speaking_evaluator.py"
click node_meme_generator "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/meme_generator/meme_generator.py"
click node_meme_validator "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/meme_generator/meme_validator.py"
click node_meme_crop "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/meme_generator/meme_crop.py"
click node_behavior_scoring "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/scoring/behavior_evaluator.py"
click node_sqlite "https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/database/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_router,node_api_client toneBlue
class node_dashboard,node_chat_ui,node_practice_ui,node_practice_tracks,node_speaking_ui,node_meme_ui,node_fast_phrases toneAmber
class node_app_factory,node_api_config,node_schemas,node_auth_routes,node_chat_routes,node_goal_routes,node_module_routes,node_speaking_routes,node_scoring_routes,node_meme_routes,node_system_routes toneMint
class node_chatbot,node_prompt_loader,node_audio_transcription,node_speaking_evaluator,node_meme_generator,node_meme_validator,node_meme_crop,node_behavior_scoring toneRose
class node_sqlite,node_firestore,node_firebase_auth,node_learner toneIndigo
```

## Components

### Web Client

- [SPA Shell](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/app.js): `UI/js/app.js`
- [Client Router](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/router.js): `UI/js/router.js`
- [API Client](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/api.js): `UI/js/api.js`

### Learning Experiences

- [Dashboard and Goals](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/dashboard.js): `UI/js/dashboard.js`
- [Chat Tutor](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/chat.js): `UI/js/chat.js`
- [Practice Arena](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/practice/modulepractice.js): `UI/js/practice/modulepractice.js`
- [CEFR Track Curricula](https://github.com/rifatjahanazad-bd/ai-english-coach/tree/main/UI/js/practice): `UI/js/practice`
- [Speaking Simulator](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/memescreen.js): `UI/js/memescreen.js`
- [Meme Learning](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/UI/js/memescreen.js): `UI/js/memescreen.js`
- [Fast Phrases Game](https://github.com/rifatjahanazad-bd/ai-english-coach/tree/main/UI/js): `UI/js`

### API Services

- [FastAPI Application](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/app.py): `backend/api/app.py`
- [API Configuration](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/config.py): `backend/api/config.py`
- [Request Schemas](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/models/schemas.py): `backend/api/models/schemas.py`
- [Authentication Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/auth.py): `backend/api/routes/auth.py`
- [Chat Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/chat.py): `backend/api/routes/chat.py`
- [Goal Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/goals.py): `backend/api/routes/goals.py`
- [Module Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/modules.py): `backend/api/routes/modules.py`
- [Speaking Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/speaking.py): `backend/api/routes/speaking.py`
- [Scoring Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/scoring.py): `backend/api/routes/scoring.py`
- [Meme Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/memes.py): `backend/api/routes/memes.py`
- [System Routes](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/api/routes/system.py): `backend/api/routes/system.py`

### AI and Processing

- [Tutor Engine](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/chatbot.py): `backend/chatbot.py`
- [Prompt Loader](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/prompt_loader.py): `backend/prompt_loader.py`
- [Audio Transcription](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/audio_to_txt.py): `backend/audio_to_txt.py`
- [Speaking Evaluator](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/mp3_txt_speaking_evaluator.py): `backend/mp3_txt_speaking_evaluator.py`
- [Meme Generator](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/meme_generator/meme_generator.py): `backend/meme_generator/meme_generator.py`
- [Image Validator](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/meme_generator/meme_validator.py): `backend/meme_generator/meme_validator.py`
- [Image Cropper](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/meme_generator/meme_crop.py): `backend/meme_generator/meme_crop.py`
- [Behavior Scoring](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/scoring/behavior_evaluator.py): `backend/scoring/behavior_evaluator.py`

### Persistence and Sync

- [SQLite Database](https://github.com/rifatjahanazad-bd/ai-english-coach/blob/main/backend/database/db.py): `backend/database/db.py`
- **Firestore**
- **Firebase Auth**

### Other components

- **Learner**

## Connections

- Learner → SPA Shell: uses (evidence: `README.md`)
- SPA Shell → Client Router: routes through (evidence: `README.md`)
- Client Router → Dashboard and Goals: selects view (evidence: `README.md`)
- Client Router → Practice Arena: opens practice (evidence: `README.md`)
- Client Router → Speaking Simulator: opens test (evidence: `README.md`)
- Client Router → Fast Phrases Game: opens game (evidence: `README.md`)
- Practice Arena → CEFR Track Curricula: loads drills
- Chat Tutor → API Client: requests chat
- Dashboard and Goals → API Client: requests goals
- Practice Arena → API Client: requests modules
- Speaking Simulator → API Client: submits audio
- Meme Learning → API Client: requests memes
- API Client → FastAPI Application: calls API (evidence: `README.md`)
- FastAPI Application → API Configuration: loads settings (evidence: `backend/api/app.py`)
- FastAPI Application → Chat Routes: registers routes
- FastAPI Application → Module Routes: registers routes
- FastAPI Application → Speaking Routes: registers routes
- FastAPI Application → Meme Routes: registers routes
- FastAPI Application → Authentication Routes: registers routes
- FastAPI Application → Goal Routes: registers routes
- FastAPI Application → Scoring Routes: registers routes
- FastAPI Application → System Routes: registers routes
- Authentication Routes → Request Schemas: validates with (evidence: `backend/api/routes/auth.py`)
- Authentication Routes → SQLite Database: reads and writes (evidence: `backend/api/routes/auth.py`)
- Module Routes → SQLite Database: loads curriculum (evidence: `backend/api/routes/modules.py`)
- Chat Routes → Tutor Engine: dispatches to
- Tutor Engine → Prompt Loader: loads prompts (evidence: `backend/chatbot.py`)
- Tutor Engine → SQLite Database: stores history (evidence: `backend/chatbot.py`)
- Goal Routes → SQLite Database: reads and writes
- Speaking Routes → Speaking Evaluator: evaluates speech (evidence: `backend/api/routes/speaking.py`)
- Speaking Routes → Audio Transcription: verifies audio (evidence: `backend/api/routes/speaking.py`)
- Speaking Evaluator → Audio Transcription: transcribes audio (evidence: `backend/mp3_txt_speaking_evaluator.py`)
- Speaking Evaluator → Prompt Loader: loads prompts (evidence: `backend/mp3_txt_speaking_evaluator.py`)
- Meme Routes → Meme Generator: generates memes (evidence: `backend/api/routes/memes.py`)
- Meme Routes → Image Validator: validates images (evidence: `backend/api/routes/memes.py`)
- Meme Routes → Image Cropper: crops images (evidence: `backend/api/routes/memes.py`)
- Meme Routes → SQLite Database: tracks quotas (evidence: `backend/api/routes/memes.py`)
- Meme Generator → Image Validator: checks output (evidence: `backend/meme_generator/meme_generator.py`)
- Meme Generator → Image Cropper: crops output (evidence: `backend/meme_generator/meme_generator.py`)
- Scoring Routes → Behavior Scoring: evaluates events (evidence: `backend/api/routes/scoring.py`)
- Behavior Scoring → SQLite Database: loads and saves (evidence: `backend/scoring/behavior_evaluator.py`)
- Learner → Firebase Auth: signs in (evidence: `README.md`)
- Firebase Auth → Firestore: authenticates (evidence: `README.md`)
- Firestore → SPA Shell: syncs live state (evidence: `README.md`)