# luc7o/yachay-play architecture

> Architecture diagram of the GitHub repository luc7o/yachay-play, 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/luc7o/yachay-play
- Repository: https://github.com/luc7o/yachay-play

## Overview

YachayPlay supports teacher-led classroom activities: teachers create coded games, students join and play, and results feed into history and statistics. The map includes Ludo and Crossword live play, browser-based Word Lightning, teacher tools, accounts, question banks, profiles, and live collaborative slides. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements; unsampled integrations and tools are represented without speculative call chains.

Main entry points: [`frontend/src/api.js`](https://github.com/luc7o/yachay-play/blob/main/frontend/src/api.js) (HTTP API Client), [`frontend/src/App.jsx`](https://github.com/luc7o/yachay-play/blob/main/frontend/src/App.jsx) (App Navigation), [`frontend/src/cw/CrosswordGame.jsx`](https://github.com/luc7o/yachay-play/blob/main/frontend/src/cw/CrosswordGame.jsx) (Crossword Screens), [`backend/db.js`](https://github.com/luc7o/yachay-play/blob/main/backend/db.js) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Accounts"]
  node_app["App Navigation<br/>[App.jsx]"]
  node_authui["Sign-in Screen<br/>[AuthScreen.jsx]"]
  node_api["HTTP API Client<br/>[api.js]"]
  node_socketclient["Socket Client<br/>[socket.js]"]
  node_catalog["Game Catalog<br/>[GameCatalog.jsx]"]
end

subgraph group_games["Classroom Games"]
  node_ludoui["Ludo Screens<br/>[EngineerGame.jsx]"]
  node_board["Ludo Board Data<br/>[board.js]"]
  node_crosswordui["Crossword Screens<br/>[CrosswordGame.jsx]"]
  node_crosswords["Word Bank<br/>[words.js]"]
  node_wordgame["Word Lightning"]
end

subgraph group_learning["Teacher Tools"]
  node_slidesui["Live Slides<br/>[Estudio.jsx]"]
  node_teacherkit["Classroom Tools<br/>[Pizarra.jsx]"]
  node_timer["Activity Timer<br/>[cronometroStore.js]"]
  node_questionui["Question Bank UI<br/>[QuestionBank.jsx]"]
end

subgraph group_services["Backend Services"]
  node_authroutes["Authentication Routes<br/>[auth.js]"]
  node_identity["User and Tokens<br/>[authCore.js]"]
  node_ludoserver["Ludo Game Server<br/>[server.js]"]
  node_crossroutes["Crossword Routes<br/>[routes.js]"]
  node_crossengine["Crossword Engine<br/>[engine.js]"]
  node_slidesengine["Slides Engine<br/>[engine.js]"]
  node_slidesmodel["Slide Operations<br/>[model.js]"]
  node_slidesroutes["Slides Routes<br/>[routes.js]"]
  node_slidesockets["Slides Sockets<br/>[sockets.js]"]
  node_questions["Question Bank Service<br/>[questionBank.js]"]
  node_profile["Profile and Ranking<br/>[profile.js]"]
  node_stats["Class Statistics<br/>[stats.js]"]
  node_assistant["AI Assistant<br/>[assistant.js]"]
end

subgraph group_state["Persistence"]
  node_crosspersist["Crossword Persistence<br/>[persist.js]"]
  node_slidespersist["Slides Persistence<br/>[persist.js]"]
  node_database[("PostgreSQL<br/>[db.js]")]
end

node_teacher(("Teacher"))
node_student(("Student"))

node_teacher -->|"uses"| node_app
node_student -->|"uses"| node_app
node_app -->|"shows"| node_authui
node_app -->|"navigates"| node_catalog
node_app -->|"calls"| node_api
node_app -->|"uses"| node_socketclient
node_authui -->|"calls"| node_api
node_api -->|"HTTP requests"| node_authroutes
node_authroutes -->|"authenticates"| node_identity
node_identity -->|"reads and writes"| node_database
node_teacher -->|"hosts"| node_ludoui
node_student -->|"plays"| node_ludoui
node_app -->|"shows"| node_ludoui
node_api -->|"game requests"| node_ludoserver
node_socketclient -->|"live events"| node_ludoserver
node_ludoserver -->|"uses board map"| node_board
node_teacher -->|"creates game"| node_crosswordui
node_student -->|"joins and plays"| node_crosswordui
node_app -->|"shows"| node_crosswordui
node_crosswordui -->|"requests rooms"| node_api
node_crosswordui -->|"joins live play"| node_socketclient
node_api -->|"HTTP requests"| node_crossroutes
node_crossroutes -->|"creates and looks up"| node_crossengine
node_crossengine -->|"selects words"| node_crosswords
node_crossengine -->|"room persistence"| node_crosspersist
node_crosspersist -->|"stores results"| node_database
node_student -->|"plays in browser"| node_wordgame
node_teacher -->|"leads activity"| node_slidesui
node_student -->|"collaborates"| node_slidesui
node_slidesui -->|"uses HTTP"| node_api
node_slidesui -->|"uses live events"| node_socketclient
node_slidesroutes -->|"calls"| node_slidesengine
node_slidesockets -->|"updates rooms"| node_slidesengine
node_slidesengine -->|"applies operations"| node_slidesmodel
node_slidespersist -->|"persists rooms"| node_slidesengine
node_slidespersist -->|"stores rooms"| node_database
node_teacher -->|"uses tools"| node_teacherkit
node_teacher -->|"uses timer"| node_timer
node_teacher -->|"manages questions"| node_questionui
node_questionui -.->|"calls"| node_api
node_api -->|"HTTP requests"| node_questions
node_questions -->|"stores questions"| node_database
node_questions -->|"official and teacher questions"| node_teacher
node_teacher -->|"views results"| node_stats
node_student -->|"views history"| node_stats
node_api -.->|"HTTP requests"| node_stats
node_stats -.->|"reads results"| node_database
node_teacher -->|"manages profile"| node_profile

click node_app "https://github.com/luc7o/yachay-play/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/luc7o/yachay-play/blob/main/frontend/src/AuthScreen.jsx"
click node_api "https://github.com/luc7o/yachay-play/blob/main/frontend/src/api.js"
click node_socketclient "https://github.com/luc7o/yachay-play/blob/main/frontend/src/socket.js"
click node_catalog "https://github.com/luc7o/yachay-play/blob/main/frontend/src/GameCatalog.jsx"
click node_authroutes "https://github.com/luc7o/yachay-play/blob/main/backend/auth.js"
click node_identity "https://github.com/luc7o/yachay-play/blob/main/backend/authCore.js"
click node_ludoui "https://github.com/luc7o/yachay-play/blob/main/frontend/src/ludo/EngineerGame.jsx"
click node_ludoserver "https://github.com/luc7o/yachay-play/blob/main/backend/server.js"
click node_board "https://github.com/luc7o/yachay-play/blob/main/backend/board.js"
click node_crosswordui "https://github.com/luc7o/yachay-play/blob/main/frontend/src/cw/CrosswordGame.jsx"
click node_crossroutes "https://github.com/luc7o/yachay-play/blob/main/backend/crossword/routes.js"
click node_crossengine "https://github.com/luc7o/yachay-play/blob/main/backend/crossword/engine.js"
click node_crosswords "https://github.com/luc7o/yachay-play/blob/main/backend/crossword/words.js"
click node_crosspersist "https://github.com/luc7o/yachay-play/blob/main/backend/crossword/persist.js"
click node_wordgame "https://github.com/luc7o/yachay-play/blob/main/frontend/src/PalabraRelampago.jsx"
click node_slidesui "https://github.com/luc7o/yachay-play/blob/main/frontend/src/estudio/Estudio.jsx"
click node_slidesengine "https://github.com/luc7o/yachay-play/blob/main/backend/slides/engine.js"
click node_slidesmodel "https://github.com/luc7o/yachay-play/blob/main/backend/slides/model.js"
click node_slidespersist "https://github.com/luc7o/yachay-play/blob/main/backend/slides/persist.js"
click node_slidesroutes "https://github.com/luc7o/yachay-play/blob/main/backend/slides/routes.js"
click node_slidesockets "https://github.com/luc7o/yachay-play/blob/main/backend/slides/sockets.js"
click node_teacherkit "https://github.com/luc7o/yachay-play/blob/main/frontend/src/Pizarra.jsx"
click node_timer "https://github.com/luc7o/yachay-play/blob/main/frontend/src/cronometroStore.js"
click node_questionui "https://github.com/luc7o/yachay-play/blob/main/frontend/src/QuestionBank.jsx"
click node_questions "https://github.com/luc7o/yachay-play/blob/main/backend/questionBank.js"
click node_profile "https://github.com/luc7o/yachay-play/blob/main/backend/profile.js"
click node_stats "https://github.com/luc7o/yachay-play/blob/main/backend/stats.js"
click node_assistant "https://github.com/luc7o/yachay-play/blob/main/backend/assistant.js"
click node_database "https://github.com/luc7o/yachay-play/blob/main/backend/db.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_authui,node_api,node_socketclient,node_catalog toneBlue
class node_ludoui,node_board,node_crosswordui,node_crosswords,node_wordgame toneAmber
class node_slidesui,node_teacherkit,node_timer,node_questionui toneMint
class node_authroutes,node_identity,node_ludoserver,node_crossroutes,node_crossengine,node_slidesengine,node_slidesmodel,node_slidesroutes,node_slidesockets,node_questions,node_profile,node_stats,node_assistant toneRose
class node_crosspersist,node_slidespersist,node_database,node_teacher,node_student toneIndigo
```

## Components

### App and Accounts

- [App Navigation](https://github.com/luc7o/yachay-play/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in Screen](https://github.com/luc7o/yachay-play/blob/main/frontend/src/AuthScreen.jsx): `frontend/src/AuthScreen.jsx`
- [HTTP API Client](https://github.com/luc7o/yachay-play/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Socket Client](https://github.com/luc7o/yachay-play/blob/main/frontend/src/socket.js): `frontend/src/socket.js`
- [Game Catalog](https://github.com/luc7o/yachay-play/blob/main/frontend/src/GameCatalog.jsx): `frontend/src/GameCatalog.jsx`

### Classroom Games

- [Ludo Screens](https://github.com/luc7o/yachay-play/blob/main/frontend/src/ludo/EngineerGame.jsx): `frontend/src/ludo/EngineerGame.jsx`
- [Ludo Board Data](https://github.com/luc7o/yachay-play/blob/main/backend/board.js): `backend/board.js`
- [Crossword Screens](https://github.com/luc7o/yachay-play/blob/main/frontend/src/cw/CrosswordGame.jsx): `frontend/src/cw/CrosswordGame.jsx`
- [Word Bank](https://github.com/luc7o/yachay-play/blob/main/backend/crossword/words.js): `backend/crossword/words.js`
- [Word Lightning](https://github.com/luc7o/yachay-play/blob/main/frontend/src/PalabraRelampago.jsx): `frontend/src/PalabraRelampago.jsx`

### Teacher Tools

- [Live Slides](https://github.com/luc7o/yachay-play/blob/main/frontend/src/estudio/Estudio.jsx): `frontend/src/estudio/Estudio.jsx`
- [Classroom Tools](https://github.com/luc7o/yachay-play/blob/main/frontend/src/Pizarra.jsx): `frontend/src/Pizarra.jsx`
- [Activity Timer](https://github.com/luc7o/yachay-play/blob/main/frontend/src/cronometroStore.js): `frontend/src/cronometroStore.js`
- [Question Bank UI](https://github.com/luc7o/yachay-play/blob/main/frontend/src/QuestionBank.jsx): `frontend/src/QuestionBank.jsx`

### Backend Services

- [Authentication Routes](https://github.com/luc7o/yachay-play/blob/main/backend/auth.js): `backend/auth.js`
- [User and Tokens](https://github.com/luc7o/yachay-play/blob/main/backend/authCore.js): `backend/authCore.js`
- [Ludo Game Server](https://github.com/luc7o/yachay-play/blob/main/backend/server.js): `backend/server.js`
- [Crossword Routes](https://github.com/luc7o/yachay-play/blob/main/backend/crossword/routes.js): `backend/crossword/routes.js`
- [Crossword Engine](https://github.com/luc7o/yachay-play/blob/main/backend/crossword/engine.js): `backend/crossword/engine.js`
- [Slides Engine](https://github.com/luc7o/yachay-play/blob/main/backend/slides/engine.js): `backend/slides/engine.js`
- [Slide Operations](https://github.com/luc7o/yachay-play/blob/main/backend/slides/model.js): `backend/slides/model.js`
- [Slides Routes](https://github.com/luc7o/yachay-play/blob/main/backend/slides/routes.js): `backend/slides/routes.js`
- [Slides Sockets](https://github.com/luc7o/yachay-play/blob/main/backend/slides/sockets.js): `backend/slides/sockets.js`
- [Question Bank Service](https://github.com/luc7o/yachay-play/blob/main/backend/questionBank.js): `backend/questionBank.js`
- [Profile and Ranking](https://github.com/luc7o/yachay-play/blob/main/backend/profile.js): `backend/profile.js`
- [Class Statistics](https://github.com/luc7o/yachay-play/blob/main/backend/stats.js): `backend/stats.js`
- [AI Assistant](https://github.com/luc7o/yachay-play/blob/main/backend/assistant.js): `backend/assistant.js`

### Persistence

- [Crossword Persistence](https://github.com/luc7o/yachay-play/blob/main/backend/crossword/persist.js): `backend/crossword/persist.js`
- [Slides Persistence](https://github.com/luc7o/yachay-play/blob/main/backend/slides/persist.js): `backend/slides/persist.js`
- [PostgreSQL](https://github.com/luc7o/yachay-play/blob/main/backend/db.js): `backend/db.js`

### Other components

- **Teacher**
- **Student**

## Connections

- Teacher → App Navigation: uses
- Student → App Navigation: uses
- App Navigation → Sign-in Screen: shows (evidence: `frontend/src/App.jsx`)
- App Navigation → Game Catalog: navigates (evidence: `frontend/src/App.jsx`)
- App Navigation → HTTP API Client: calls (evidence: `frontend/src/App.jsx`)
- App Navigation → Socket Client: uses (evidence: `frontend/src/App.jsx`)
- Sign-in Screen → HTTP API Client: calls (evidence: `frontend/src/AuthScreen.jsx`)
- HTTP API Client → Authentication Routes: HTTP requests (evidence: `frontend/src/api.js`)
- Authentication Routes → User and Tokens: authenticates (evidence: `backend/auth.js`)
- User and Tokens → PostgreSQL: reads and writes (evidence: `backend/authCore.js`)
- Teacher → Ludo Screens: hosts
- Student → Ludo Screens: plays
- App Navigation → Ludo Screens: shows (evidence: `frontend/src/App.jsx`)
- HTTP API Client → Ludo Game Server: game requests (evidence: `frontend/src/api.js`)
- Socket Client → Ludo Game Server: live events
- Ludo Game Server → Ludo Board Data: uses board map (evidence: `backend/server.js`)
- Teacher → Crossword Screens: creates game
- Student → Crossword Screens: joins and plays
- App Navigation → Crossword Screens: shows (evidence: `frontend/src/App.jsx`)
- Crossword Screens → HTTP API Client: requests rooms (evidence: `frontend/src/cw/CrosswordGame.jsx`)
- Crossword Screens → Socket Client: joins live play (evidence: `frontend/src/cw/CrosswordGame.jsx`)
- HTTP API Client → Crossword Routes: HTTP requests (evidence: `frontend/src/api.js`)
- Crossword Routes → Crossword Engine: creates and looks up (evidence: `backend/crossword/routes.js`)
- Crossword Engine → Word Bank: selects words (evidence: `backend/crossword/engine.js`)
- Crossword Engine → Crossword Persistence: room persistence (evidence: `backend/server.js`)
- Crossword Persistence → PostgreSQL: stores results (evidence: `backend/crossword/persist.js`)
- Student → Word Lightning: plays in browser
- Teacher → Live Slides: leads activity
- Student → Live Slides: collaborates
- Live Slides → HTTP API Client: uses HTTP (evidence: `frontend/src/estudio/Estudio.jsx`)
- Live Slides → Socket Client: uses live events (evidence: `frontend/src/estudio/Estudio.jsx`)
- Slides Routes → Slides Engine: calls (evidence: `backend/slides/routes.js`)
- Slides Sockets → Slides Engine: updates rooms (evidence: `backend/slides/sockets.js`)
- Slides Engine → Slide Operations: applies operations (evidence: `backend/slides/engine.js`)
- Slides Persistence → Slides Engine: persists rooms (evidence: `backend/slides/persist.js`)
- Slides Persistence → PostgreSQL: stores rooms (evidence: `backend/slides/persist.js`)
- Teacher → Classroom Tools: uses tools
- Teacher → Activity Timer: uses timer
- Teacher → Question Bank UI: manages questions
- Question Bank UI → HTTP API Client: calls
- HTTP API Client → Question Bank Service: HTTP requests (evidence: `frontend/src/api.js`)
- Question Bank Service → PostgreSQL: stores questions (evidence: `backend/questionBank.js`)
- Question Bank Service → Teacher: official and teacher questions
- Teacher → Class Statistics: views results
- Student → Class Statistics: views history
- HTTP API Client → Class Statistics: HTTP requests
- Class Statistics → PostgreSQL: reads results
- Teacher → Profile and Ranking: manages profile
