# meettomb/voco-mern architecture

> Architecture diagram of the GitHub repository meettomb/voco-mern, 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/meettomb/voco-mern
- Repository: https://github.com/meettomb/voco-mern

## Overview

VOCO is a language-learning platform with structured lessons, vocabulary, assessments, progress tracking, and AI voice conversations. Learners use the React app to select languages, study content, take exams, and practise conversations; the Express API handles application requests and persists learning and conversation data. Conversation practice sends messages through the backend to Ollama, while speech recognition and synthesis are provided by separate services. The README documents the overall service topology; sampled files show selected routing, model, and worker relationships, but not every controller or speech-service integration.

Main entry points: [`backend/app.js`](https://github.com/meettomb/voco-mern/blob/main/backend/app.js) (Express API), [`src/App.js`](https://github.com/meettomb/voco-mern/blob/main/src/App.js) (React application), [`backend/controller/ExamAttemptController.js`](https://github.com/meettomb/voco-mern/blob/main/backend/controller/ExamAttemptController.js) (Exam attempts), [`src/services/aiService.js`](https://github.com/meettomb/voco-mern/blob/main/src/services/aiService.js) (Conversation API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner app"]
  node_react["React application<br/>[App.js]"]
end

subgraph group_learning["Learning activities"]
  node_admin["Content administration<br/>[AddWords.js]"]
  node_lessons["Chapters and words"]
  node_languages["Learning languages"]
  node_mcq["MCQ assessments<br/>[McqsController.js]"]
  node_exams["Exam attempts"]
  node_progress[("Learner progress")]
  node_dashboard["Dashboard<br/>[dashboardFacade.js]"]
end

subgraph group_backend["Backend services"]
  node_auth["Authentication"]
  node_api["Express API<br/>[app.js]"]
  node_mongo[("MongoDB<br/>[db.js]")]
end

subgraph group_conversation["AI conversation"]
  node_aiui["Conversation UI"]
  node_aihooks["Conversation hook"]
  node_aiservice["Conversation API client<br/>[aiService.js]"]
  node_conversations["Conversation endpoints"]
  node_convcontroller["Conversation handling"]
  node_worker["Report worker"]
  node_ollama["Ollama Qwen3"]
end

subgraph group_speech["Speech services"]
  node_stt["Speech recognition<br/>[app.py]"]
  node_tts["Speech synthesis<br/>[app.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_react
node_react -->|"requests"| node_api
node_api -->|"persists data"| node_mongo
node_react -.->|"registers and signs in"| node_auth
node_react -.->|"manages content"| node_admin
node_api -->|"routes requests"| node_lessons
node_api -->|"routes requests"| node_languages
node_api -->|"routes requests"| node_mcq
node_api -->|"routes requests"| node_exams
node_api -->|"routes requests"| node_dashboard
node_lessons -->|"reads and updates"| node_languages
node_exams -->|"selects questions"| node_mcq
node_exams -->|"updates progress"| node_progress
node_react -->|"routes conversation page"| node_aiui
node_aiui -->|"loads client"| node_aiservice
node_aihooks -->|"calls"| node_aiservice
node_aiservice -->|"sends conversation requests"| node_api
node_api -->|"routes requests"| node_conversations
node_conversations -->|"dispatches"| node_convcontroller
node_worker -->|"requests analysis"| node_ollama
node_worker -->|"loads and saves reports"| node_mongo
node_api -.->|"generates replies"| node_ollama
node_api -.->|"recognizes speech"| node_stt
node_api -.->|"synthesizes speech"| node_tts

click node_react "https://github.com/meettomb/voco-mern/blob/main/src/App.js"
click node_auth "https://github.com/meettomb/voco-mern/blob/main/backend/controller/UserTableController.js"
click node_admin "https://github.com/meettomb/voco-mern/blob/main/src/Components/admin/words/AddWords.js"
click node_lessons "https://github.com/meettomb/voco-mern/blob/main/backend/controller/LearningWordsController.js"
click node_languages "https://github.com/meettomb/voco-mern/blob/main/backend/controller/LearningLanguagesController.js"
click node_mcq "https://github.com/meettomb/voco-mern/blob/main/backend/controller/McqsController.js"
click node_exams "https://github.com/meettomb/voco-mern/blob/main/backend/controller/ExamAttemptController.js"
click node_progress "https://github.com/meettomb/voco-mern/blob/main/backend/model/UserProgressModel.js"
click node_dashboard "https://github.com/meettomb/voco-mern/blob/main/backend/services/facade/dashboardFacade.js"
click node_api "https://github.com/meettomb/voco-mern/blob/main/backend/app.js"
click node_mongo "https://github.com/meettomb/voco-mern/blob/main/backend/db.js"
click node_aiui "https://github.com/meettomb/voco-mern/blob/main/src/Components/profile/Conversation/SingleConversation.js"
click node_aihooks "https://github.com/meettomb/voco-mern/blob/main/src/hooks/useAIConversation.js"
click node_aiservice "https://github.com/meettomb/voco-mern/blob/main/src/services/aiService.js"
click node_conversations "https://github.com/meettomb/voco-mern/blob/main/backend/routes/conversationRoutes.js"
click node_convcontroller "https://github.com/meettomb/voco-mern/blob/main/backend/controller/ConversationController.js"
click node_worker "https://github.com/meettomb/voco-mern/blob/main/backend/workers/ConversationWorker.js"
click node_stt "https://github.com/meettomb/voco-mern/blob/main/stt/app.py"
click node_tts "https://github.com/meettomb/voco-mern/blob/main/tts/app.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_react toneBlue
class node_admin,node_lessons,node_languages,node_mcq,node_exams,node_progress,node_dashboard toneAmber
class node_auth,node_api,node_mongo toneMint
class node_aiui,node_aihooks,node_aiservice,node_conversations,node_convcontroller,node_worker,node_ollama toneRose
class node_stt,node_tts,node_learner toneIndigo
```

## Components

### Learner app

- [React application](https://github.com/meettomb/voco-mern/blob/main/src/App.js): `src/App.js`

### Learning activities

- [Content administration](https://github.com/meettomb/voco-mern/blob/main/src/Components/admin/words/AddWords.js): `src/Components/admin/words/AddWords.js`
- [Chapters and words](https://github.com/meettomb/voco-mern/blob/main/backend/controller/LearningWordsController.js): `backend/controller/LearningWordsController.js`
- [Learning languages](https://github.com/meettomb/voco-mern/blob/main/backend/controller/LearningLanguagesController.js): `backend/controller/LearningLanguagesController.js`
- [MCQ assessments](https://github.com/meettomb/voco-mern/blob/main/backend/controller/McqsController.js): `backend/controller/McqsController.js`
- [Exam attempts](https://github.com/meettomb/voco-mern/blob/main/backend/controller/ExamAttemptController.js): `backend/controller/ExamAttemptController.js`
- [Learner progress](https://github.com/meettomb/voco-mern/blob/main/backend/model/UserProgressModel.js): `backend/model/UserProgressModel.js`
- [Dashboard](https://github.com/meettomb/voco-mern/blob/main/backend/services/facade/dashboardFacade.js): `backend/services/facade/dashboardFacade.js`

### Backend services

- [Authentication](https://github.com/meettomb/voco-mern/blob/main/backend/controller/UserTableController.js): `backend/controller/UserTableController.js`
- [Express API](https://github.com/meettomb/voco-mern/blob/main/backend/app.js): `backend/app.js`
- [MongoDB](https://github.com/meettomb/voco-mern/blob/main/backend/db.js): `backend/db.js`

### AI conversation

- [Conversation UI](https://github.com/meettomb/voco-mern/blob/main/src/Components/profile/Conversation/SingleConversation.js): `src/Components/profile/Conversation/SingleConversation.js`
- [Conversation hook](https://github.com/meettomb/voco-mern/blob/main/src/hooks/useAIConversation.js): `src/hooks/useAIConversation.js`
- [Conversation API client](https://github.com/meettomb/voco-mern/blob/main/src/services/aiService.js): `src/services/aiService.js`
- [Conversation endpoints](https://github.com/meettomb/voco-mern/blob/main/backend/routes/conversationRoutes.js): `backend/routes/conversationRoutes.js`
- [Conversation handling](https://github.com/meettomb/voco-mern/blob/main/backend/controller/ConversationController.js): `backend/controller/ConversationController.js`
- [Report worker](https://github.com/meettomb/voco-mern/blob/main/backend/workers/ConversationWorker.js): `backend/workers/ConversationWorker.js`
- **Ollama Qwen3**

### Speech services

- [Speech recognition](https://github.com/meettomb/voco-mern/blob/main/stt/app.py): `stt/app.py`
- [Speech synthesis](https://github.com/meettomb/voco-mern/blob/main/tts/app.py): `tts/app.py`

### Other components

- **Learner**

## Connections

- Learner → React application: uses (evidence: `README.md`)
- React application → Express API: requests (evidence: `README.md`)
- Express API → MongoDB: persists data (evidence: `README.md`)
- React application → Authentication: registers and signs in
- React application → Content administration: manages content (evidence: `src/App.js`)
- Express API → Chapters and words: routes requests (evidence: `backend/app.js`)
- Express API → Learning languages: routes requests (evidence: `backend/app.js`)
- Express API → MCQ assessments: routes requests (evidence: `backend/app.js`)
- Express API → Exam attempts: routes requests (evidence: `backend/app.js`)
- Express API → Dashboard: routes requests (evidence: `backend/app.js`)
- Chapters and words → Learning languages: reads and updates (evidence: `backend/controller/LearningWordsController.js`)
- Exam attempts → MCQ assessments: selects questions (evidence: `backend/controller/ExamAttemptController.js`)
- Exam attempts → Learner progress: updates progress (evidence: `backend/controller/ExamAttemptController.js`)
- React application → Conversation UI: routes conversation page (evidence: `src/App.js`)
- Conversation UI → Conversation API client: loads client (evidence: `src/Components/profile/Conversation/SingleConversation.js`)
- Conversation hook → Conversation API client: calls (evidence: `src/hooks/useAIConversation.js`)
- Conversation API client → Express API: sends conversation requests (evidence: `src/services/aiService.js`)
- Express API → Conversation endpoints: routes requests (evidence: `backend/app.js`)
- Conversation endpoints → Conversation handling: dispatches (evidence: `backend/routes/conversationRoutes.js`)
- Report worker → Ollama Qwen3: requests analysis (evidence: `backend/workers/ConversationWorker.js`)
- Report worker → MongoDB: loads and saves reports (evidence: `backend/workers/ConversationWorker.js`)
- Express API → Ollama Qwen3: generates replies
- Express API → Speech recognition: recognizes speech
- Express API → Speech synthesis: synthesizes speech