# mohandgl53/chess_mastery architecture

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

- Interactive diagram: https://gitdiagram.com/mohandgl53/chess_mastery
- Repository: https://github.com/mohandgl53/chess_mastery

## Overview

Chess Mastery is a full-stack chess training platform. Players enter through the React app to play and analyze games, study lessons and puzzles, track progress, and request AI coaching; the frontend also runs Stockfish locally for chess evaluation. Backend APIs support accounts, learning, games, player memory, and coaching, with PostgreSQL persistence and a RAG knowledge base. The graph combines explicit README capabilities with shown imports and calls; unsampled subsystem links are omitted where their wiring could not be verified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/App.tsx) (App Router), [`backend/src/app.ts`](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/app.ts) (Express API), [`frontend/src/services/chessEngine.ts`](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/chessEngine.ts) (Chess Engine), [`frontend/src/pages/PlayPage.tsx`](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PlayPage.tsx) (Play Games)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chess Client"]
  node_app["App Router<br/>[App.tsx]"]
  node_api["API Client<br/>[client.ts]"]
end

subgraph group_chess["Chess Training"]
  node_play["Play Games<br/>[PlayPage.tsx]"]
  node_analyze["Game Analysis<br/>[AnalyzePage.tsx]"]
  node_review["Game Review"]
  node_engine["Chess Engine<br/>[chessEngine.ts]"]
  node_stockfish["Stockfish Worker"]
  node_learn["Lessons<br/>[LearnPage.tsx]"]
  node_lesson["Lesson Study<br/>[LessonPage.tsx]"]
  node_practice["Practice Drills<br/>[PracticePage.tsx]"]
  node_puzzles["Tactical Puzzles<br/>[PuzzlesPage.tsx]"]
  node_progress["Progress Tracking<br/>[ProgressPage.tsx]"]
  node_profile["Player Profile<br/>[ProfilePage.tsx]"]
end

subgraph group_api["Backend API"]
  node_backend["Express API<br/>[app.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_authcontroller["Auth Endpoints<br/>[auth.controller.ts]"]
  node_curriculum["Curriculum Services"]
  node_practicebackend["Practice Services"]
  node_gamebackend["Game Services<br/>[game.service.ts]"]
  node_playerbackend["Player Memory"]
  node_database[("PostgreSQL<br/>[database.ts]")]
  node_coachapi["Coach API<br/>[coachApi.ts]"]
end

subgraph group_intelligence["Coaching Intelligence"]
  node_coach["Coach Service<br/>[LLMCoachService.ts]"]
  node_coachbackend["Coach Backend<br/>[coach.service.ts]"]
  node_retrieval["RAG Retrieval"]
  node_ingestion["Knowledge Ingestion"]
  node_embedding["Embedding Provider"]
  node_knowledge[("Chess Knowledge<br/>[database.ts]")]
end

node_player(("Player"))

node_player -->|"uses"| node_app
node_app -->|"routes to"| node_play
node_app -->|"routes to"| node_analyze
node_app -->|"routes to"| node_learn
node_app -->|"routes to"| node_lesson
node_app -->|"routes to"| node_practice
node_app -->|"routes to"| node_puzzles
node_app -->|"routes to"| node_progress
node_app -->|"routes to"| node_profile
node_play -.->|"uses"| node_engine
node_analyze -.->|"uses"| node_engine
node_play -.->|"reviews game"| node_review
node_engine -->|"loads"| node_stockfish
node_coach -->|"gets candidates"| node_engine
node_coach -->|"requests coaching"| node_coachapi
node_coachapi -->|"calls API"| node_backend
node_backend -->|"configures"| node_database
node_backend -->|"mounts routes"| node_authcontroller
node_authcontroller -->|"calls"| node_auth
node_auth -->|"uses"| node_database
node_backend -.->|"serves curriculum"| node_curriculum
node_backend -.->|"serves practice"| node_practicebackend
node_backend -.->|"serves games"| node_gamebackend
node_backend -.->|"serves player data"| node_playerbackend
node_backend -.->|"serves coaching"| node_coachbackend
node_coachbackend -.->|"retrieves knowledge"| node_retrieval
node_retrieval -->|"creates embeddings"| node_embedding
node_retrieval -->|"searches chunks"| node_knowledge
node_ingestion -->|"creates embeddings"| node_embedding
node_ingestion -->|"stores chunks"| node_knowledge
node_knowledge -.->|"shares PostgreSQL"| node_database

click node_app "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/App.tsx"
click node_play "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PlayPage.tsx"
click node_analyze "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/AnalyzePage.tsx"
click node_review "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/components/game/GameReviewModal.tsx"
click node_engine "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/chessEngine.ts"
click node_stockfish "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/StockfishEngineService.ts"
click node_learn "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/LearnPage.tsx"
click node_lesson "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/LessonPage.tsx"
click node_practice "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PracticePage.tsx"
click node_puzzles "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PuzzlesPage.tsx"
click node_progress "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/ProgressPage.tsx"
click node_profile "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/ProfilePage.tsx"
click node_api "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/api/client.ts"
click node_backend "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/app.ts"
click node_auth "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/auth.service.ts"
click node_authcontroller "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/controllers/auth.controller.ts"
click node_curriculum "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/curriculum.service.ts"
click node_practicebackend "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/practice.service.ts"
click node_gamebackend "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/game.service.ts"
click node_playerbackend "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/player-memory.service.ts"
click node_database "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/config/database.ts"
click node_coach "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/LLMCoachService.ts"
click node_coachapi "https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/api/coachApi.ts"
click node_coachbackend "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/coach.service.ts"
click node_retrieval "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/rag.retrieval.service.ts"
click node_ingestion "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/knowledge.ingestion.service.ts"
click node_embedding "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/providers/embedding/embedding.factory.ts"
click node_knowledge "https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/config/database.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_app,node_api toneBlue
class node_play,node_analyze,node_review,node_engine,node_stockfish,node_learn,node_lesson,node_practice,node_puzzles,node_progress,node_profile toneAmber
class node_backend,node_auth,node_authcontroller,node_curriculum,node_practicebackend,node_gamebackend,node_playerbackend,node_database,node_coachapi toneMint
class node_coach,node_coachbackend,node_retrieval,node_ingestion,node_embedding,node_knowledge toneRose
class node_player toneIndigo
```

## Components

### Chess Client

- [App Router](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/api/client.ts): `frontend/src/services/api/client.ts`

### Chess Training

- [Play Games](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PlayPage.tsx): `frontend/src/pages/PlayPage.tsx`
- [Game Analysis](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/AnalyzePage.tsx): `frontend/src/pages/AnalyzePage.tsx`
- [Game Review](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/components/game/GameReviewModal.tsx): `frontend/src/components/game/GameReviewModal.tsx`
- [Chess Engine](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/chessEngine.ts): `frontend/src/services/chessEngine.ts`
- [Stockfish Worker](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/StockfishEngineService.ts): `frontend/src/services/StockfishEngineService.ts`
- [Lessons](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/LearnPage.tsx): `frontend/src/pages/LearnPage.tsx`
- [Lesson Study](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/LessonPage.tsx): `frontend/src/pages/LessonPage.tsx`
- [Practice Drills](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PracticePage.tsx): `frontend/src/pages/PracticePage.tsx`
- [Tactical Puzzles](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/PuzzlesPage.tsx): `frontend/src/pages/PuzzlesPage.tsx`
- [Progress Tracking](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/ProgressPage.tsx): `frontend/src/pages/ProgressPage.tsx`
- [Player Profile](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/pages/ProfilePage.tsx): `frontend/src/pages/ProfilePage.tsx`

### Backend API

- [Express API](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Authentication](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [Auth Endpoints](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/controllers/auth.controller.ts): `backend/src/controllers/auth.controller.ts`
- [Curriculum Services](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/curriculum.service.ts): `backend/src/services/curriculum.service.ts`
- [Practice Services](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/practice.service.ts): `backend/src/services/practice.service.ts`
- [Game Services](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/game.service.ts): `backend/src/services/game.service.ts`
- [Player Memory](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/player-memory.service.ts): `backend/src/services/player-memory.service.ts`
- [PostgreSQL](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/config/database.ts): `backend/src/config/database.ts`
- [Coach API](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/api/coachApi.ts): `frontend/src/services/api/coachApi.ts`

### Coaching Intelligence

- [Coach Service](https://github.com/mohandgl53/chess_mastery/blob/main/frontend/src/services/LLMCoachService.ts): `frontend/src/services/LLMCoachService.ts`
- [Coach Backend](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/coach.service.ts): `backend/src/services/coach.service.ts`
- [RAG Retrieval](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/rag.retrieval.service.ts): `backend/src/services/rag.retrieval.service.ts`
- [Knowledge Ingestion](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/services/knowledge.ingestion.service.ts): `backend/src/services/knowledge.ingestion.service.ts`
- [Embedding Provider](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/providers/embedding/embedding.factory.ts): `backend/src/providers/embedding/embedding.factory.ts`
- [Chess Knowledge](https://github.com/mohandgl53/chess_mastery/blob/main/backend/src/config/database.ts): `backend/src/config/database.ts`

### Other components

- **Player**

## Connections

- Player → App Router: uses (evidence: `README.md`)
- App Router → Play Games: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Game Analysis: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Lessons: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Lesson Study: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Practice Drills: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Tactical Puzzles: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Progress Tracking: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Player Profile: routes to (evidence: `frontend/src/App.tsx`)
- Play Games → Chess Engine: uses
- Game Analysis → Chess Engine: uses
- Play Games → Game Review: reviews game
- Chess Engine → Stockfish Worker: loads (evidence: `frontend/src/services/chessEngine.ts`)
- Coach Service → Chess Engine: gets candidates (evidence: `frontend/src/services/LLMCoachService.ts`)
- Coach Service → Coach API: requests coaching (evidence: `frontend/src/services/LLMCoachService.ts`)
- Coach API → Express API: calls API (evidence: `README.md`)
- Express API → PostgreSQL: configures (evidence: `backend/src/app.ts`)
- Express API → Auth Endpoints: mounts routes (evidence: `backend/src/app.ts`)
- Auth Endpoints → Authentication: calls (evidence: `backend/src/controllers/auth.controller.ts`)
- Authentication → PostgreSQL: uses (evidence: `backend/src/services/auth.service.ts`)
- Express API → Curriculum Services: serves curriculum
- Express API → Practice Services: serves practice
- Express API → Game Services: serves games
- Express API → Player Memory: serves player data
- Express API → Coach Backend: serves coaching
- Coach Backend → RAG Retrieval: retrieves knowledge
- RAG Retrieval → Embedding Provider: creates embeddings (evidence: `backend/src/services/rag.retrieval.service.ts`)
- RAG Retrieval → Chess Knowledge: searches chunks (evidence: `backend/src/services/rag.retrieval.service.ts`)
- Knowledge Ingestion → Embedding Provider: creates embeddings (evidence: `backend/src/services/knowledge.ingestion.service.ts`)
- Knowledge Ingestion → Chess Knowledge: stores chunks (evidence: `backend/src/services/knowledge.ingestion.service.ts`)
- Chess Knowledge → PostgreSQL: shares PostgreSQL (evidence: `backend/src/config/database.ts`)
