# goldmangrey/aluaielts architecture

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

- Interactive diagram: https://gitdiagram.com/goldmangrey/aluaielts
- Repository: https://github.com/goldmangrey/aluaielts

## Overview

Alua is a language-learning product with iOS and web clients backed by a FastAPI service. The principal learner flow is to use a client to access learning activities, submit practice or review outcomes, and consult plans and progress; the backend exposes distinct curriculum, exercise, vocabulary-review, reading, listening, and writing capabilities. Planning and progress aggregation form a useful internal layer. The source index confirms API router registration and several module dependencies; client-to-server and many unsampled module interactions are shown only as unverified links, not inspected call chains.

Main entry points: [`backend/app/api.py`](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/api.py) (API router), [`backend/app/modules/progress/engine.py`](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/progress/engine.py) (Progress aggregation), [`web/src/app/page.tsx`](https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/page.tsx) (Web learning app), [`backend/app/main.py`](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Learner clients"]
  node_ios["iOS app<br/>[AluaApp.swift]"]
  node_ios_network["iOS API client<br/>[APIClient.swift]"]
  node_web["Web learning app<br/>[page.tsx]"]
  node_web_proxy["Web API proxy<br/>[route.ts]"]
end

subgraph group_platform["API platform"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_router["API router<br/>[api.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_enrollment["Device enrollment"]
  node_database[("Database models<br/>[models.py]")]
end

subgraph group_learning["Learning content"]
  node_curriculum["Curriculum"]
  node_grammar["Grammar lessons"]
  node_vocabulary["Vocabulary review<br/>[service.py]"]
  node_study["Study content<br/>[service.py]"]
end

subgraph group_practice["Practice and assessment"]
  node_exercises["Exercises<br/>[service.py]"]
  node_reading["Reading exams<br/>[service.py]"]
  node_listening["Listening practice"]
  node_writing["Writing assessment<br/>[router.py]"]
  node_ai_worker["AI review routes<br/>[route.ts]"]
end

subgraph group_planning["Planning and progress"]
  node_events["Learning events"]
  node_daily_plan["Daily planning<br/>[engine.py]"]
  node_mastery["Mastery tracking<br/>[engine.py]"]
  node_progress["Progress aggregation<br/>[engine.py]"]
end

node_learner(("Learner"))

node_learner -.->|"uses"| node_ios
node_learner -.->|"uses"| node_web
node_ios -.->|"requests through"| node_ios_network
node_ios_network -.->|"sends API requests"| node_api_app
node_web -.->|"uses routes"| node_web_proxy
node_web_proxy -.->|"forwards requests"| node_api_app
node_api_app -->|"includes"| node_api_router
node_api_router -->|"registers routes"| node_curriculum
node_api_router -->|"registers routes"| node_grammar
node_api_router -.->|"registers routes"| node_vocabulary
node_api_router -.->|"registers routes"| node_study
node_api_router -->|"registers routes"| node_exercises
node_api_router -->|"registers routes"| node_reading
node_api_router -->|"registers routes"| node_listening
node_api_router -.->|"registers routes"| node_writing
node_api_router -->|"registers routes"| node_enrollment
node_api_router -.->|"uses"| node_auth
node_vocabulary -.->|"uses persistence"| node_database
node_reading -.->|"uses persistence"| node_database
node_daily_plan -->|"provides plan models"| node_progress
node_events -->|"provides event models"| node_progress
node_mastery -->|"provides mastery models"| node_progress
node_api_router -->|"registers routes"| node_events
node_api_router -->|"registers routes"| node_daily_plan
node_api_router -->|"registers routes"| node_mastery
node_api_router -->|"registers routes"| node_progress
node_web -.->|"uses AI review"| node_ai_worker

click node_ios "https://github.com/goldmangrey/aluaielts/blob/main/frontend/Alua/App/AluaApp.swift"
click node_ios_network "https://github.com/goldmangrey/aluaielts/blob/main/frontend/Alua/Core/Networking/APIClient.swift"
click node_web "https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/page.tsx"
click node_web_proxy "https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/api/alua/%5B...path%5D/route.ts"
click node_api_app "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/main.py"
click node_api_router "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/api.py"
click node_auth "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/core/auth.py"
click node_enrollment "https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/enrollment"
click node_curriculum "https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/curriculum"
click node_grammar "https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/grammar"
click node_vocabulary "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/vocabulary_review/service.py"
click node_study "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/study/service.py"
click node_exercises "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/exercises/service.py"
click node_reading "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/reading/service.py"
click node_listening "https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/listening"
click node_writing "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/writing/router.py"
click node_events "https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/learning_events"
click node_daily_plan "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/daily_plan/engine.py"
click node_mastery "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/mastery/engine.py"
click node_progress "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/progress/engine.py"
click node_database "https://github.com/goldmangrey/aluaielts/blob/main/backend/app/db/models.py"
click node_ai_worker "https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/api/reading/explain/route.ts"

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_ios,node_ios_network,node_web,node_web_proxy toneBlue
class node_api_app,node_api_router,node_auth,node_enrollment,node_database toneAmber
class node_curriculum,node_grammar,node_vocabulary,node_study toneMint
class node_exercises,node_reading,node_listening,node_writing,node_ai_worker toneRose
class node_events,node_daily_plan,node_mastery,node_progress,node_learner toneIndigo
```

## Components

### Learner clients

- [iOS app](https://github.com/goldmangrey/aluaielts/blob/main/frontend/Alua/App/AluaApp.swift): `frontend/Alua/App/AluaApp.swift`
- [iOS API client](https://github.com/goldmangrey/aluaielts/blob/main/frontend/Alua/Core/Networking/APIClient.swift): `frontend/Alua/Core/Networking/APIClient.swift`
- [Web learning app](https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`
- [Web API proxy](https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/api/alua/%5B...path%5D/route.ts): `web/src/app/api/alua/[...path]/route.ts`

### API platform

- [FastAPI application](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/api.py): `backend/app/api.py`
- [Authentication](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Device enrollment](https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/enrollment): `backend/app/modules/enrollment`
- [Database models](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### Learning content

- [Curriculum](https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/curriculum): `backend/app/modules/curriculum`
- [Grammar lessons](https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/grammar): `backend/app/modules/grammar`
- [Vocabulary review](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/vocabulary_review/service.py): `backend/app/modules/vocabulary_review/service.py`
- [Study content](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/study/service.py): `backend/app/modules/study/service.py`

### Practice and assessment

- [Exercises](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/exercises/service.py): `backend/app/modules/exercises/service.py`
- [Reading exams](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/reading/service.py): `backend/app/modules/reading/service.py`
- [Listening practice](https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/listening): `backend/app/modules/listening`
- [Writing assessment](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/writing/router.py): `backend/app/modules/writing/router.py`
- [AI review routes](https://github.com/goldmangrey/aluaielts/blob/main/web/src/app/api/reading/explain/route.ts): `web/src/app/api/reading/explain/route.ts`

### Planning and progress

- [Learning events](https://github.com/goldmangrey/aluaielts/tree/main/backend/app/modules/learning_events): `backend/app/modules/learning_events`
- [Daily planning](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/daily_plan/engine.py): `backend/app/modules/daily_plan/engine.py`
- [Mastery tracking](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/mastery/engine.py): `backend/app/modules/mastery/engine.py`
- [Progress aggregation](https://github.com/goldmangrey/aluaielts/blob/main/backend/app/modules/progress/engine.py): `backend/app/modules/progress/engine.py`

### Other components

- **Learner**

## Connections

- Learner → iOS app: uses
- Learner → Web learning app: uses
- iOS app → iOS API client: requests through
- iOS API client → FastAPI application: sends API requests
- Web learning app → Web API proxy: uses routes
- Web API proxy → FastAPI application: forwards requests
- FastAPI application → API router: includes (evidence: `backend/app/main.py`)
- API router → Curriculum: registers routes (evidence: `backend/app/api.py`)
- API router → Grammar lessons: registers routes (evidence: `backend/app/api.py`)
- API router → Vocabulary review: registers routes
- API router → Study content: registers routes
- API router → Exercises: registers routes (evidence: `backend/app/api.py`)
- API router → Reading exams: registers routes (evidence: `backend/app/api.py`)
- API router → Listening practice: registers routes (evidence: `backend/app/api.py`)
- API router → Writing assessment: registers routes (evidence: `backend/app/api.py`)
- API router → Device enrollment: registers routes (evidence: `backend/app/api.py`)
- API router → Authentication: uses
- Vocabulary review → Database models: uses persistence
- Reading exams → Database models: uses persistence
- Daily planning → Progress aggregation: provides plan models (evidence: `backend/app/modules/progress/engine.py`)
- Learning events → Progress aggregation: provides event models (evidence: `backend/app/modules/progress/engine.py`)
- Mastery tracking → Progress aggregation: provides mastery models (evidence: `backend/app/modules/progress/engine.py`)
- API router → Learning events: registers routes (evidence: `backend/app/api.py`)
- API router → Daily planning: registers routes (evidence: `backend/app/api.py`)
- API router → Mastery tracking: registers routes (evidence: `backend/app/api.py`)
- API router → Progress aggregation: registers routes (evidence: `backend/app/api.py`)
- Web learning app → AI review routes: uses AI review
