# ahamie71/language_app architecture

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

- Interactive diagram: https://gitdiagram.com/ahamie71/language_app
- Repository: https://github.com/ahamie71/language_app
- Video tour (about a minute): https://gitdiagram.com/ahamie71/language_app/video

## Overview

Duolingua is a web language-learning app whose main loop is a learner chatting with an AI coach: the backend persists messages, calls the AI service for a reply and supporting translation/explanation, and stores the result. The frontend also offers direct, one-shot practice activities, alongside vocabulary, flashcards, dictation, and progress tracking. The README documents the AI service’s route/controller/model layers and local model runtimes. Some feature modules were not sampled, so their internal connections are shown only where documented.

Main entry points: [`ai_service/controllers`](https://github.com/ahamie71/language_app/tree/main/ai_service/controllers) (AI feature logic), [`backend/src/controllers/conversationController.js`](https://github.com/ahamie71/language_app/blob/main/backend/src/controllers/conversationController.js) (Conversation handling), [`frontend/src/App.jsx`](https://github.com/ahamie71/language_app/blob/main/frontend/src/App.jsx) (App and routes), [`frontend/src/services/api.js`](https://github.com/ahamie71/language_app/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learning frontend"]
  node_app["App and routes<br/>[App.jsx]"]
  node_conversation_ui["Conversation<br/>[Conversation.jsx]"]
  node_practice_ui["Practice activities<br/>[Exercises.jsx]"]
  node_learning_ui["Learning dashboard<br/>[Dashboard.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_backend["Application backend"]
  node_server["HTTP API<br/>[server.js]"]
  node_conversation_backend["Conversation handling"]
  node_vocabulary_backend["Vocabulary and SRS"]
  node_ai_gateway["AI gateway<br/>[aiService.js]"]
end

subgraph group_ai["AI service"]
  node_ai_entry["Flask route registry<br/>[app.py]"]
  node_ai_routes["Feature endpoints"]
  node_ai_controllers["AI feature logic"]
  node_llm["LLM client<br/>[llm.py]"]
  node_translation["NLLB translation<br/>[translation.py]"]
  node_intent["Intent classifier<br/>[intent.py]"]
  node_speech["Speech synthesis<br/>[speech.py]"]
  node_transcription["Speech transcription<br/>[transcription.py]"]
  node_device["Device selection<br/>[device.py]"]
  node_language_maps["Language model maps"]
end

subgraph group_runtime["Data and models"]
  node_database[("MySQL persistence<br/>[database.js]")]
  node_models["Domain models<br/>[index.js]"]
  node_ollama["Ollama LLM runtime"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_conversation_ui
node_app -->|"routes to"| node_practice_ui
node_conversation_ui -->|"calls"| node_api_client
node_practice_ui -->|"calls directly"| node_ai_entry
node_learning_ui -.->|"uses"| node_api_client
node_api_client -->|"calls REST"| node_server
node_server -->|"routes to"| node_conversation_backend
node_conversation_backend -->|"requests AI"| node_ai_gateway
node_conversation_backend -->|"extracts vocabulary"| node_vocabulary_backend
node_conversation_backend -->|"reads and writes"| node_models
node_vocabulary_backend -->|"reads and writes"| node_models
node_models -->|"uses Sequelize"| node_database
node_ai_gateway -->|"calls endpoints"| node_ai_entry
node_ai_entry -->|"registers"| node_ai_routes
node_ai_routes -->|"dispatches"| node_ai_controllers
node_ai_controllers -->|"uses"| node_llm
node_ai_controllers -->|"uses"| node_translation
node_ai_controllers -->|"uses"| node_intent
node_ai_controllers -->|"uses"| node_speech
node_ai_controllers -->|"uses"| node_transcription
node_translation -->|"selects device"| node_device
node_speech -->|"selects device"| node_device
node_transcription -->|"loads language maps"| node_language_maps
node_llm -->|"HTTP chat"| node_ollama
node_ai_controllers -->|"uses language maps"| node_language_maps

click node_app "https://github.com/ahamie71/language_app/blob/main/frontend/src/App.jsx"
click node_conversation_ui "https://github.com/ahamie71/language_app/blob/main/frontend/src/pages/Conversation.jsx"
click node_practice_ui "https://github.com/ahamie71/language_app/blob/main/frontend/src/pages/Exercises.jsx"
click node_learning_ui "https://github.com/ahamie71/language_app/blob/main/frontend/src/pages/Dashboard.jsx"
click node_api_client "https://github.com/ahamie71/language_app/blob/main/frontend/src/services/api.js"
click node_server "https://github.com/ahamie71/language_app/blob/main/backend/src/server.js"
click node_conversation_backend "https://github.com/ahamie71/language_app/blob/main/backend/src/controllers/conversationController.js"
click node_vocabulary_backend "https://github.com/ahamie71/language_app/blob/main/backend/src/controllers/vocabularyController.js"
click node_ai_gateway "https://github.com/ahamie71/language_app/blob/main/backend/src/services/aiService.js"
click node_ai_entry "https://github.com/ahamie71/language_app/blob/main/ai_service/app.py"
click node_ai_routes "https://github.com/ahamie71/language_app/tree/main/ai_service/routes"
click node_ai_controllers "https://github.com/ahamie71/language_app/tree/main/ai_service/controllers"
click node_llm "https://github.com/ahamie71/language_app/blob/main/ai_service/services/llm.py"
click node_translation "https://github.com/ahamie71/language_app/blob/main/ai_service/services/translation.py"
click node_intent "https://github.com/ahamie71/language_app/blob/main/ai_service/services/intent.py"
click node_speech "https://github.com/ahamie71/language_app/blob/main/ai_service/services/speech.py"
click node_transcription "https://github.com/ahamie71/language_app/blob/main/ai_service/services/transcription.py"
click node_device "https://github.com/ahamie71/language_app/blob/main/ai_service/services/device.py"
click node_language_maps "https://github.com/ahamie71/language_app/tree/main/ai_service/language"
click node_database "https://github.com/ahamie71/language_app/blob/main/backend/src/config/database.js"
click node_models "https://github.com/ahamie71/language_app/blob/main/backend/src/models/index.js"

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_app,node_conversation_ui,node_practice_ui,node_learning_ui,node_api_client toneBlue
class node_server,node_conversation_backend,node_vocabulary_backend,node_ai_gateway toneAmber
class node_ai_entry,node_ai_routes,node_ai_controllers,node_llm,node_translation,node_intent,node_speech,node_transcription,node_device,node_language_maps toneMint
class node_database,node_models,node_ollama toneRose
class node_learner toneIndigo
```

## Components

### Learning frontend

- [App and routes](https://github.com/ahamie71/language_app/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Conversation](https://github.com/ahamie71/language_app/blob/main/frontend/src/pages/Conversation.jsx): `frontend/src/pages/Conversation.jsx`
- [Practice activities](https://github.com/ahamie71/language_app/blob/main/frontend/src/pages/Exercises.jsx): `frontend/src/pages/Exercises.jsx`
- [Learning dashboard](https://github.com/ahamie71/language_app/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [API client](https://github.com/ahamie71/language_app/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Application backend

- [HTTP API](https://github.com/ahamie71/language_app/blob/main/backend/src/server.js): `backend/src/server.js`
- [Conversation handling](https://github.com/ahamie71/language_app/blob/main/backend/src/controllers/conversationController.js): `backend/src/controllers/conversationController.js`
- [Vocabulary and SRS](https://github.com/ahamie71/language_app/blob/main/backend/src/controllers/vocabularyController.js): `backend/src/controllers/vocabularyController.js`
- [AI gateway](https://github.com/ahamie71/language_app/blob/main/backend/src/services/aiService.js): `backend/src/services/aiService.js`

### AI service

- [Flask route registry](https://github.com/ahamie71/language_app/blob/main/ai_service/app.py): `ai_service/app.py`
- [Feature endpoints](https://github.com/ahamie71/language_app/tree/main/ai_service/routes): `ai_service/routes`
- [AI feature logic](https://github.com/ahamie71/language_app/tree/main/ai_service/controllers): `ai_service/controllers`
- [LLM client](https://github.com/ahamie71/language_app/blob/main/ai_service/services/llm.py): `ai_service/services/llm.py`
- [NLLB translation](https://github.com/ahamie71/language_app/blob/main/ai_service/services/translation.py): `ai_service/services/translation.py`
- [Intent classifier](https://github.com/ahamie71/language_app/blob/main/ai_service/services/intent.py): `ai_service/services/intent.py`
- [Speech synthesis](https://github.com/ahamie71/language_app/blob/main/ai_service/services/speech.py): `ai_service/services/speech.py`
- [Speech transcription](https://github.com/ahamie71/language_app/blob/main/ai_service/services/transcription.py): `ai_service/services/transcription.py`
- [Device selection](https://github.com/ahamie71/language_app/blob/main/ai_service/services/device.py): `ai_service/services/device.py`
- [Language model maps](https://github.com/ahamie71/language_app/tree/main/ai_service/language): `ai_service/language`

### Data and models

- [MySQL persistence](https://github.com/ahamie71/language_app/blob/main/backend/src/config/database.js): `backend/src/config/database.js`
- [Domain models](https://github.com/ahamie71/language_app/blob/main/backend/src/models/index.js): `backend/src/models/index.js`
- **Ollama LLM runtime**

### Other components

- **Learner**

## Connections

- Learner → App and routes: uses (evidence: `README.md`)
- App and routes → Conversation: routes to (evidence: `frontend/src/App.jsx`)
- App and routes → Practice activities: routes to (evidence: `frontend/src/App.jsx`)
- Conversation → API client: calls (evidence: `README.md`)
- Practice activities → Flask route registry: calls directly (evidence: `README.md`)
- Learning dashboard → API client: uses
- API client → HTTP API: calls REST (evidence: `README.md`)
- HTTP API → Conversation handling: routes to (evidence: `backend/src/server.js`)
- Conversation handling → AI gateway: requests AI (evidence: `backend/src/controllers/conversationController.js`)
- Conversation handling → Vocabulary and SRS: extracts vocabulary (evidence: `backend/src/controllers/conversationController.js`)
- Conversation handling → Domain models: reads and writes (evidence: `backend/src/controllers/conversationController.js`)
- Vocabulary and SRS → Domain models: reads and writes (evidence: `backend/src/controllers/vocabularyController.js`)
- Domain models → MySQL persistence: uses Sequelize
- AI gateway → Flask route registry: calls endpoints (evidence: `backend/src/services/aiService.js`)
- Flask route registry → Feature endpoints: registers (evidence: `ai_service/app.py`)
- Feature endpoints → AI feature logic: dispatches (evidence: `README.md`)
- AI feature logic → LLM client: uses (evidence: `README.md`)
- AI feature logic → NLLB translation: uses (evidence: `README.md`)
- AI feature logic → Intent classifier: uses (evidence: `README.md`)
- AI feature logic → Speech synthesis: uses (evidence: `README.md`)
- AI feature logic → Speech transcription: uses (evidence: `README.md`)
- NLLB translation → Device selection: selects device (evidence: `ai_service/services/translation.py`)
- Speech synthesis → Device selection: selects device (evidence: `ai_service/services/speech.py`)
- Speech transcription → Language model maps: loads language maps (evidence: `ai_service/services/transcription.py`)
- LLM client → Ollama LLM runtime: HTTP chat (evidence: `ai_service/services/llm.py`)
- AI feature logic → Language model maps: uses language maps (evidence: `README.md`)
