# victorbro/ft_transcendence architecture

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

- Interactive diagram: https://gitdiagram.com/victorbro/ft_transcendence
- Repository: https://github.com/victorbro/ft_transcendence

## Overview

ft_transcendence is an AI-driven language-learning platform. Its intended learner journey is account creation, course setup, adaptive CEFR placement, a level-specific roadmap, and AI-assisted practice; profile and two-factor settings support that journey. The API also includes session/authentication, course, question-generation, placement, and storage services. The README documents live learner chat and progress analytics, but the supplied tree and excerpts do not establish their runtime wiring. Arrows are limited to shown calls/imports or README-described capabilities; omitted implementation excerpts leave some links unverified.

Main entry points: [`apps/api/src/placement/placement.controller.ts`](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement.controller.ts) (Placement orchestration), [`apps/web/lib`](https://github.com/victorbro/ft_transcendence/tree/main/apps/web/lib) (Browser API clients), [`apps/api/src/app.module.ts`](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/app.module.ts) (API application), [`apps/api/src/prisma/prisma.service.ts`](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/prisma/prisma.service.ts) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Learner experience"]
  node_web_learning["Learning screens"]
  node_web_auth["Account screens"]
  node_web_chat["Chat and friends"]
  node_web_clients["Browser API clients"]
end

subgraph group_api["Platform API"]
  node_api_app["API application<br/>[app.module.ts]"]
  node_auth["Authentication<br/>[auth.controller.ts]"]
  node_users["User profiles"]
end

subgraph group_learning["Learning services"]
  node_courses["Course management"]
  node_placement["Placement orchestration"]
  node_placement_sessions["Exam sessions"]
  node_placement_questions["Adaptive questions"]
  node_placement_progress["Placement progress"]
  node_question_generation["Question generation"]
  node_llm["AI provider<br/>[llm.provider.ts]"]
  node_roadmap_tutor["Roadmap and AI tutor"]
  node_live_progress["Live practice and analytics"]
end

subgraph group_infra["Shared state and contracts"]
  node_prisma[("Database access<br/>[prisma.service.ts]")]
  node_redis[("Redis state<br/>[redis.service.ts]")]
  node_contracts["Shared schemas"]
end

node_learner(("Learner"))

node_learner -->|"signs in"| node_web_auth
node_learner -.->|"learns"| node_web_learning
node_learner -.->|"practices live"| node_web_chat
node_web_auth -.->|"uses"| node_web_clients
node_web_learning -.->|"uses"| node_web_clients
node_web_clients -->|"calls auth API"| node_auth
node_web_clients -->|"calls profile API"| node_users
node_web_learning -.->|"starts placement"| node_placement
node_api_app -->|"registers"| node_auth
node_api_app -->|"registers"| node_users
node_api_app -->|"registers"| node_courses
node_api_app -->|"registers"| node_placement
node_auth -->|"queries users"| node_prisma
node_users -.->|"updates users"| node_prisma
node_courses -->|"queries courses"| node_prisma
node_placement -.->|"manages sessions"| node_placement_sessions
node_placement -.->|"advances questions"| node_placement_questions
node_placement -.->|"tracks progress"| node_placement_progress
node_placement_sessions -->|"stores sessions"| node_redis
node_placement_questions -.->|"requests questions"| node_question_generation
node_question_generation -->|"generates batches"| node_llm
node_question_generation -->|"stores questions"| node_prisma
node_roadmap_tutor -.->|"teaches"| node_learner
node_live_progress -.->|"shows progress"| node_learner
node_contracts -.->|"validates responses"| node_web_clients

click node_web_learning "https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(dashboard)/learn"
click node_web_auth "https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(main)"
click node_web_chat "https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(mode)"
click node_web_clients "https://github.com/victorbro/ft_transcendence/tree/main/apps/web/lib"
click node_api_app "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/app.module.ts"
click node_auth "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/auth/auth.controller.ts"
click node_users "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/users/users.controller.ts"
click node_courses "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/courses/courses.controller.ts"
click node_placement "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement.controller.ts"
click node_placement_sessions "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement-session.service.ts"
click node_placement_questions "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement-question.service.ts"
click node_placement_progress "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement-progress.service.ts"
click node_question_generation "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/question-generation/question-stock.service.ts"
click node_llm "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/llm/llm.provider.ts"
click node_roadmap_tutor "https://github.com/victorbro/ft_transcendence/tree/main/apps/api/src"
click node_live_progress "https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(mode)"
click node_prisma "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/prisma/prisma.service.ts"
click node_redis "https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/redis/redis.service.ts"
click node_contracts "https://github.com/victorbro/ft_transcendence/tree/main/packages/shared/src/schemas"

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_learning,node_web_auth,node_web_chat,node_web_clients toneBlue
class node_api_app,node_auth,node_users toneAmber
class node_courses,node_placement,node_placement_sessions,node_placement_questions,node_placement_progress,node_question_generation,node_llm,node_roadmap_tutor,node_live_progress toneMint
class node_prisma,node_redis,node_contracts toneRose
class node_learner toneIndigo
```

## Components

### Learner experience

- [Learning screens](https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(dashboard)/learn): `apps/web/app/[locale]/(dashboard)/learn`
- [Account screens](https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(main)): `apps/web/app/[locale]/(main)`
- [Chat and friends](https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(mode)): `apps/web/app/[locale]/(mode)`
- [Browser API clients](https://github.com/victorbro/ft_transcendence/tree/main/apps/web/lib): `apps/web/lib`

### Platform API

- [API application](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`
- [Authentication](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/auth/auth.controller.ts): `apps/api/src/auth/auth.controller.ts`
- [User profiles](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/users/users.controller.ts): `apps/api/src/users/users.controller.ts`

### Learning services

- [Course management](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/courses/courses.controller.ts): `apps/api/src/courses/courses.controller.ts`
- [Placement orchestration](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement.controller.ts): `apps/api/src/placement/placement.controller.ts`
- [Exam sessions](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement-session.service.ts): `apps/api/src/placement/placement-session.service.ts`
- [Adaptive questions](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement-question.service.ts): `apps/api/src/placement/placement-question.service.ts`
- [Placement progress](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/placement/placement-progress.service.ts): `apps/api/src/placement/placement-progress.service.ts`
- [Question generation](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/question-generation/question-stock.service.ts): `apps/api/src/question-generation/question-stock.service.ts`
- [AI provider](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/llm/llm.provider.ts): `apps/api/src/llm/llm.provider.ts`
- [Roadmap and AI tutor](https://github.com/victorbro/ft_transcendence/tree/main/apps/api/src): `apps/api/src`
- [Live practice and analytics](https://github.com/victorbro/ft_transcendence/tree/main/apps/web/app/%5Blocale%5D/(mode)): `apps/web/app/[locale]/(mode)`

### Shared state and contracts

- [Database access](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/prisma/prisma.service.ts): `apps/api/src/prisma/prisma.service.ts`
- [Redis state](https://github.com/victorbro/ft_transcendence/blob/main/apps/api/src/redis/redis.service.ts): `apps/api/src/redis/redis.service.ts`
- [Shared schemas](https://github.com/victorbro/ft_transcendence/tree/main/packages/shared/src/schemas): `packages/shared/src/schemas`

### Other components

- **Learner**

## Connections

- Learner → Account screens: signs in
- Learner → Learning screens: learns (evidence: `README.md`)
- Learner → Chat and friends: practices live (evidence: `README.md`)
- Account screens → Browser API clients: uses
- Learning screens → Browser API clients: uses
- Browser API clients → Authentication: calls auth API (evidence: `apps/web/lib/auth-client.ts`)
- Browser API clients → User profiles: calls profile API (evidence: `apps/web/lib/auth-client.ts`)
- Learning screens → Placement orchestration: starts placement (evidence: `README.md`)
- API application → Authentication: registers (evidence: `apps/api/src/app.module.ts`)
- API application → User profiles: registers (evidence: `apps/api/src/app.module.ts`)
- API application → Course management: registers (evidence: `apps/api/src/app.module.ts`)
- API application → Placement orchestration: registers (evidence: `apps/api/src/app.module.ts`)
- Authentication → Database access: queries users
- User profiles → Database access: updates users
- Course management → Database access: queries courses
- Placement orchestration → Exam sessions: manages sessions
- Placement orchestration → Adaptive questions: advances questions
- Placement orchestration → Placement progress: tracks progress
- Exam sessions → Redis state: stores sessions (evidence: `apps/api/src/placement/placement-session.service.ts`)
- Adaptive questions → Question generation: requests questions
- Question generation → AI provider: generates batches (evidence: `apps/api/src/question-generation/question-stock.service.ts`)
- Question generation → Database access: stores questions (evidence: `apps/api/src/question-generation/question-stock.service.ts`)
- Roadmap and AI tutor → Learner: teaches (evidence: `README.md`)
- Live practice and analytics → Learner: shows progress (evidence: `README.md`)
- Shared schemas → Browser API clients: validates responses
