# yvanol-fotso/english-coach-ai architecture

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

- Interactive diagram: https://gitdiagram.com/yvanol-fotso/english-coach-ai
- Repository: https://github.com/yvanol-fotso/english-coach-ai

## Overview

English Coach AI is a local-first language-learning app: learners use SvelteKit pages and API proxies, FastAPI routes, an Ollama language model, and SQLite or Postgres. The product spans conversation and correction, a guided course, question answering, studio tools, translation, voice drills, vocabulary review, and saved history/progress. The sampled chat route shows its orchestration of prompts, the model, and persistence; other feature branches are preserved from the README and tree. Unread modules limit the evidence for their internal calls.

Main entry points: [`backend/app/api/routes/chat.py`](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/routes/chat.py) (Chat orchestration), [`backend/app/api/routes`](https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/api/routes) (Feature routes), [`frontend/src/routes`](https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/routes) (SvelteKit pages), [`backend/app/main.py`](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/main.py) (Application startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_web["SvelteKit pages"]
  node_proxy["API proxies"]
  node_chatui["Conversation UI"]
  node_courseui["Course UI"]
  node_practiceui["Practice UI"]
end

subgraph group_api["Backend API"]
  node_apiroot["API router<br/>[router.py]"]
  node_chatroute["Chat orchestration<br/>[chat.py]"]
  node_routes["Feature routes"]
  node_deps["Request dependencies<br/>[deps.py]"]
end

subgraph group_learning["Learning services"]
  node_prompts["Prompt design<br/>[prompts.py]"]
  node_catalog["Learning catalog"]
  node_schemas["Learning schemas"]
  node_speech["Speech processing<br/>[speech.py]"]
end

subgraph group_state["Learner state"]
  node_database[("Relational database<br/>[models.py]")]
  node_session["Database sessions<br/>[session.py]"]
  node_conversations["Conversation storage<br/>[conversations.py]"]
  node_activities["Activity tracking<br/>[activities.py]"]
  node_words["Vocabulary review<br/>[words.py]"]
end

subgraph group_runtime["Local runtime"]
  node_ollama["Ollama client<br/>[ollama.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_main["Application startup<br/>[main.py]"]
end

node_learner(("Learner"))
node_modelservice["Ollama model"]
node_localdb[("SQLite or Postgres")]

node_learner -->|"uses"| node_web
node_web -.->|"requests"| node_proxy
node_proxy -.->|"forwards requests"| node_apiroot
node_apiroot -->|"registers routes"| node_routes
node_apiroot -->|"registers chat"| node_chatroute
node_chatui -.->|"supports conversation"| node_web
node_courseui -.->|"supports course"| node_web
node_practiceui -.->|"supports drills"| node_web
node_main -->|"mounts router"| node_apiroot
node_main -->|"initializes database"| node_session
node_main -->|"creates client"| node_ollama
node_main -->|"creates service"| node_speech
node_main -->|"reads settings"| node_config
node_session -->|"creates tables"| node_database
node_session -->|"opens connection"| node_localdb
node_chatroute -->|"loads and saves"| node_conversations
node_chatroute -->|"logs speaking"| node_activities
node_chatroute -->|"builds prompts"| node_prompts
node_chatroute -->|"requests response"| node_ollama
node_chatroute -->|"uses injected services"| node_deps
node_ollama -->|"sends model requests"| node_modelservice
node_web -.->|"offers learning features"| node_routes
node_routes -.->|"handles voice features"| node_speech
node_routes -.->|"supports vocabulary"| node_words
node_routes -.->|"serves course and tool content"| node_catalog
node_routes -.->|"validates feature data"| node_schemas
node_conversations -.->|"persists conversations"| node_database
node_activities -.->|"persists progress"| node_database
node_words -.->|"persists reviews"| node_database

click node_web "https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/routes"
click node_proxy "https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/routes/api"
click node_chatui "https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/lib/components/chat"
click node_courseui "https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/lib/components/path"
click node_practiceui "https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/lib/components/practice"
click node_apiroot "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/router.py"
click node_chatroute "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/routes/chat.py"
click node_routes "https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/api/routes"
click node_deps "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/deps.py"
click node_prompts "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/services/prompts.py"
click node_catalog "https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/catalog"
click node_schemas "https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/schemas"
click node_speech "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/services/speech.py"
click node_ollama "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/services/ollama.py"
click node_database "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/db/models.py"
click node_session "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/db/session.py"
click node_conversations "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/repositories/conversations.py"
click node_activities "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/repositories/activities.py"
click node_words "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/repositories/words.py"
click node_config "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/core/config.py"
click node_main "https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/main.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_web,node_proxy,node_chatui,node_courseui,node_practiceui toneBlue
class node_apiroot,node_chatroute,node_routes,node_deps,node_localdb toneAmber
class node_prompts,node_catalog,node_schemas,node_speech toneMint
class node_database,node_session,node_conversations,node_activities,node_words toneRose
class node_ollama,node_config,node_main,node_learner,node_modelservice toneIndigo
```

## Components

### Learner experience

- [SvelteKit pages](https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/routes): `frontend/src/routes`
- [API proxies](https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/routes/api): `frontend/src/routes/api`
- [Conversation UI](https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/lib/components/chat): `frontend/src/lib/components/chat`
- [Course UI](https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/lib/components/path): `frontend/src/lib/components/path`
- [Practice UI](https://github.com/yvanol-fotso/english-coach-ai/tree/main/frontend/src/lib/components/practice): `frontend/src/lib/components/practice`

### Backend API

- [API router](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Chat orchestration](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/routes/chat.py): `backend/app/api/routes/chat.py`
- [Feature routes](https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Request dependencies](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`

### Learning services

- [Prompt design](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/services/prompts.py): `backend/app/services/prompts.py`
- [Learning catalog](https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/catalog): `backend/app/catalog`
- [Learning schemas](https://github.com/yvanol-fotso/english-coach-ai/tree/main/backend/app/schemas): `backend/app/schemas`
- [Speech processing](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/services/speech.py): `backend/app/services/speech.py`

### Learner state

- [Relational database](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Database sessions](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Conversation storage](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/repositories/conversations.py): `backend/app/repositories/conversations.py`
- [Activity tracking](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/repositories/activities.py): `backend/app/repositories/activities.py`
- [Vocabulary review](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/repositories/words.py): `backend/app/repositories/words.py`

### Local runtime

- [Ollama client](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/services/ollama.py): `backend/app/services/ollama.py`
- [Runtime settings](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Application startup](https://github.com/yvanol-fotso/english-coach-ai/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Learner**
- **Ollama model**
- **SQLite or Postgres**

## Connections

- Learner → SvelteKit pages: uses
- SvelteKit pages → API proxies: requests
- API proxies → API router: forwards requests
- API router → Feature routes: registers routes (evidence: `backend/app/api/router.py`)
- API router → Chat orchestration: registers chat (evidence: `backend/app/api/router.py`)
- Conversation UI → SvelteKit pages: supports conversation
- Course UI → SvelteKit pages: supports course
- Practice UI → SvelteKit pages: supports drills
- Application startup → API router: mounts router (evidence: `backend/app/main.py`)
- Application startup → Database sessions: initializes database (evidence: `backend/app/main.py`)
- Application startup → Ollama client: creates client (evidence: `backend/app/main.py`)
- Application startup → Speech processing: creates service (evidence: `backend/app/main.py`)
- Application startup → Runtime settings: reads settings (evidence: `backend/app/main.py`)
- Database sessions → Relational database: creates tables (evidence: `backend/app/db/session.py`)
- Database sessions → SQLite or Postgres: opens connection
- Chat orchestration → Conversation storage: loads and saves (evidence: `backend/app/api/routes/chat.py`)
- Chat orchestration → Activity tracking: logs speaking (evidence: `backend/app/api/routes/chat.py`)
- Chat orchestration → Prompt design: builds prompts (evidence: `backend/app/api/routes/chat.py`)
- Chat orchestration → Ollama client: requests response (evidence: `backend/app/api/routes/chat.py`)
- Chat orchestration → Request dependencies: uses injected services (evidence: `backend/app/api/routes/chat.py`)
- Ollama client → Ollama model: sends model requests
- SvelteKit pages → Feature routes: offers learning features
- Feature routes → Speech processing: handles voice features
- Feature routes → Vocabulary review: supports vocabulary
- Feature routes → Learning catalog: serves course and tool content (evidence: `backend/app/api/routes/chat.py`)
- Feature routes → Learning schemas: validates feature data (evidence: `backend/app/api/routes/chat.py`)
- Conversation storage → Relational database: persists conversations
- Activity tracking → Relational database: persists progress (evidence: `backend/app/repositories/activities.py`)
- Vocabulary review → Relational database: persists reviews (evidence: `backend/app/repositories/words.py`)
