# patbiz-school-projects/si4_ps8_la-khet-de-l-olympe architecture

> Architecture diagram of the GitHub repository patbiz-school-projects/si4_ps8_la-khet-de-l-olympe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe
- Repository: https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe

## Overview

1. **Overall shape**
   - This is a **Node.js monorepo** with a browser/mobile front-end and several backend services.
   - The system is split into domain-focused services: **gateway, files, auth, user, game, challenge, and chats**.
   - The **gateway** is the only public backend entrypoint; everything else is internal.

2. **Client-side boundary**
   - The frontend lives under `frontend/src` and is organized by product area: **auth, home, profile, game, chat, waiting-room, shared**.
   - The front-end talks to the backend through utility wrappers for **fetch, cookies, JWT/auth handling, and events**.
   - `frontend/capacitor.config.json` suggests the UI is also prepared for a **mobile wrapper** in addition to web.

3. **Gateway role**
   - `backend/services/gateway` is the external ingress for HTTP and real-time traffic.
   - The README says it applies **CORS, body parsing, token extraction/verification, guest-token injection, and centralized error mapping**.
   - Architecturally, it is the boundary between the client and the internal services.

4. **Shared backend infrastructure**
   - `backend/helpers` contains the common plumbing used across services: **router parsing/tokenizing, middleware, repository abstraction, CORS, and an event bus**.
   - This indicates the repo avoids a heavy framework and instead uses **custom request-routing and middleware utilities**.
   - The event bus folder supports the README’s **event-driven architecture** for decoupling services.

5. **Authentication subsystem**
   - `backend/services/auth` owns **signup, login, token renewal, logout, and forgot-password**.
   - It has its own `mongo.js`, so authentication state and secrets are persisted separately from the rest of the app.
   - Other services call into auth through `userClient.js`, which suggests service-to-service coordination around identity.

6. **User/profile/social subsystem**
   - `backend/services/userService` owns **profiles, public/personal profile data, friends, connected users, achievements, and leaderboard-related stats**.
   - The structure is split into **controllers, managers, repositories, and entities**, with `mongo.js` indicating its own persistence layer.
   - This service is also responsible for the online/offline notion of users via the **connected users service**.

7. **Game subsystem**
   - `backend/services/gameService` is the authoritative game engine: **boards, cells, pieces, inventory, lasers, turns, action validation, timers, starting positions, and ELO updates**.
   - It also contains **AI logic** for solo play.
   - `GamesManager`, `PlayersManager`, and the `manager/` folder show that this service owns the **match lifecycle and rule enforcement**.

8. **Challenge subsystem**
   - `backend/services/challengeService` orchestrates **challenge creation, listing, acceptance, decline, and cancellation**.
   - It has both `http/` and `socket/` folders, so it handles **request/response APIs plus real-time challenge notifications**.
   - It bridges the social layer and game layer, using `userClient.js` and `gameClient.js` to coordinate with those services.

9. **Chat subsystem**
   - `backend/services/chats` manages **global chat and game chat**.
   - The service contains chat entities, repositories, a `ChatsManager`, and network/handler layers, which indicates it owns **membership, room state, and message history**.
   - Real-time broadcast is part of its core role, while historical access is likely exposed over HTTP.

10. **Files/static delivery**
   - `backend/services/files` is the static-content service.
   - The `front/` directory and the README indicate it serves the built front-end and shared assets, acting as the **asset delivery boundary** rather than a business service.

11. **Request and event flows**
   - Typical flow: **browser/mobile client → gateway → domain service** for CRUD-like operations.
   - Real-time flows go through **WebSocket-style connections** for gameplay, chat, and challenge notifications.
   - Cross-service side effects are handled with **Redis Pub/Sub-style events** rather than long synchronous call chains, especially for user/profile and notification updates.

12. **Data ownership and persistence**
   - Each service keeps its own domain state behind repositories or managers, rather than sharing a single application-wide model.
   - Persistence is clearly explicit in **auth** and **userService** via Mongo-related files; other services encapsulate storage behind their repositories.
   - This makes the diagram naturally **bounded-context-oriented**: identity, users, games, challenges, and chats are separate data domains.

13. **Operational packaging**
   - The repo is designed to run under **Docker Compose**; every service has a `Dockerfile`.
   - `docker-compose.yml` and the `secrets.env` pattern indicate the deployment unit is the **full service stack**, with the gateway exposed at port 8000.

Main entry points: [`frontend/src`](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src) (App shell), [`backend/services/gateway/index.js`](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/gateway/index.js) (Gateway), [`backend/helpers`](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/backend/helpers) (Helpers), [`backend/services/challengeService/index.js`](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/challengeService/index.js) (Challenge svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>frontend app"]
  node_frontend_utils["Client utils<br/>client helpers"]
  node_frontend_mobile["Mobile wrap<br/>capacitor config"]
  node_frontend_auth["Auth UI<br/>auth views"]
  node_frontend_home["Home UI<br/>home views"]
  node_frontend_profile["Profile UI<br/>profile views"]
  node_frontend_game["Game UI<br/>game views"]
  node_frontend_waiting["Waiting room<br/>match lobby"]
  node_frontend_chat["Chat UI<br/>chat views"]
  node_frontend_shared["Shared UI<br/>shared components"]
end

subgraph group_backend["Backend"]
  node_backend_helpers["Helpers<br/>shared plumbing"]
  node_backend_eventbus(("Event bus<br/>pubsub core"))
  node_backend_gateway["Gateway<br/>[index.js]"]
  node_backend_auth["Auth service<br/>identity service<br/>[index.js]"]
  node_backend_user["User service<br/>profile service<br/>[index.js]"]
  node_backend_game["Game service<br/>game engine<br/>[index.js]"]
  node_backend_challenge["Challenge svc<br/>match orchestration<br/>[index.js]"]
  node_backend_chats["Chats service<br/>chat service<br/>[index.js]"]
  node_backend_files["Files service<br/>static delivery<br/>[index.js]"]
end

node_frontend_app -->|"uses"| node_frontend_utils
node_frontend_app -->|"packs"| node_frontend_mobile
node_frontend_app -->|"contains"| node_frontend_auth
node_frontend_app -->|"contains"| node_frontend_home
node_frontend_app -->|"contains"| node_frontend_profile
node_frontend_app -->|"contains"| node_frontend_game
node_frontend_app -->|"contains"| node_frontend_waiting
node_frontend_app -->|"contains"| node_frontend_chat
node_frontend_app -->|"contains"| node_frontend_shared
node_frontend_utils -->|"calls"| node_backend_gateway
node_backend_gateway -->|"builds on"| node_backend_helpers
node_backend_auth -->|"builds on"| node_backend_helpers
node_backend_user -->|"builds on"| node_backend_helpers
node_backend_game -->|"builds on"| node_backend_helpers
node_backend_challenge -->|"builds on"| node_backend_helpers
node_backend_chats -->|"builds on"| node_backend_helpers
node_backend_files -->|"builds on"| node_backend_helpers
node_backend_user -->|"publishes"| node_backend_eventbus
node_backend_challenge -->|"publishes"| node_backend_eventbus
node_backend_chats -->|"publishes"| node_backend_eventbus
node_backend_game -->|"publishes"| node_backend_eventbus
node_backend_gateway -->|"routes"| node_backend_auth
node_backend_gateway -->|"routes"| node_backend_user
node_backend_gateway -->|"routes"| node_backend_game
node_backend_gateway -->|"routes"| node_backend_challenge
node_backend_gateway -->|"routes"| node_backend_chats
node_backend_gateway -->|"routes"| node_backend_files
node_backend_challenge -->|"uses"| node_backend_user
node_backend_challenge -->|"uses"| node_backend_game
node_backend_auth -->|"coordinates"| node_backend_user

click node_frontend_app "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src"
click node_frontend_utils "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/utils"
click node_frontend_mobile "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/frontend/capacitor.config.json"
click node_frontend_auth "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/auth"
click node_frontend_home "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/home"
click node_frontend_profile "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/profile"
click node_frontend_game "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/game"
click node_frontend_waiting "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/waiting-room"
click node_frontend_chat "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/chat"
click node_frontend_shared "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/shared"
click node_backend_helpers "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/backend/helpers"
click node_backend_eventbus "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/backend/helpers/event-bus"
click node_backend_gateway "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/gateway/index.js"
click node_backend_auth "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/auth/index.js"
click node_backend_user "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/userService/index.js"
click node_backend_game "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/gameService/index.js"
click node_backend_challenge "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/challengeService/index.js"
click node_backend_chats "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/chats/index.js"
click node_backend_files "https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/files/index.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_frontend_app,node_frontend_utils,node_frontend_mobile,node_frontend_auth,node_frontend_home,node_frontend_profile,node_frontend_game,node_frontend_waiting,node_frontend_chat,node_frontend_shared toneBlue
class node_backend_helpers,node_backend_eventbus,node_backend_gateway,node_backend_auth,node_backend_user,node_backend_game,node_backend_challenge,node_backend_chats,node_backend_files toneAmber
```

## Components

### Frontend

Browser/mobile UI and client-side utilities

- [App shell](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src): frontend app · Top-level client UI composition under frontend/src · `frontend/src`
- [Client utils](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/utils): client helpers · Fetch, auth, cookie, JWT, event, and mobile notification wrappers · `frontend/src/utils`
- [Mobile wrap](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/frontend/capacitor.config.json): capacitor config · Mobile wrapper configuration for the client UI · `frontend/capacitor.config.json`
- [Auth UI](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/auth): auth views · Login, signup, and forgot-password screens · `frontend/src/auth`
- [Home UI](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/home): home views · Home, friends, search, and leaderboard screens · `frontend/src/home`
- [Profile UI](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/profile): profile views · Personal and public profile screens · `frontend/src/profile`
- [Game UI](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/game): game views · Game board, turn, inventory, and state-machine screens · `frontend/src/game`
- [Waiting room](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/waiting-room): match lobby · Pre-game lobby and matchmaking entry screen · `frontend/src/waiting-room`
- [Chat UI](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/chat): chat views · Global and in-game chat interfaces · `frontend/src/chat`
- [Shared UI](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/frontend/src/shared): shared components · Reusable app-wide components and modal/navigation shells · `frontend/src/shared`

### Backend

Gateway, shared plumbing, and domain services

- [Helpers](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/backend/helpers): shared plumbing · Routing, middleware, repository, CORS, and request parsing utilities · `backend/helpers`
- [Event bus](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/tree/main/backend/helpers/event-bus): pubsub core · Shared event transport used for decoupled cross-service updates · `backend/helpers/event-bus`
- [Gateway](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/gateway/index.js): edge gateway · Public ingress for HTTP and real-time traffic · `backend/services/gateway/index.js`
- [Auth service](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/auth/index.js): identity service · Signup, login, renewal, logout, and password recovery · `backend/services/auth/index.js`
- [User service](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/userService/index.js): profile service · Profiles, friends, connected users, achievements, and leaderboard data · `backend/services/userService/index.js`
- [Game service](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/gameService/index.js): game engine · Authoritative match rules, board state, timers, AI, and ELO updates · `backend/services/gameService/index.js`
- [Challenge svc](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/challengeService/index.js): match orchestration · Challenge creation, acceptance, decline, cancellation, and notifications · `backend/services/challengeService/index.js`
- [Chats service](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/chats/index.js): chat service · Global chat and game chat membership, history, and broadcasts · `backend/services/chats/index.js`
- [Files service](https://github.com/patbiz-school-projects/si4_ps8_la-khet-de-l-olympe/blob/main/backend/services/files/index.js): static delivery · Serves built front-end assets and shared static content · `backend/services/files/index.js`

## Connections

- App shell → Client utils: uses · Client-side network and auth wrappers
- App shell → Mobile wrap: packs · Mobile deployment wrapper for the client
- App shell → Auth UI: contains · Auth-related screens and flows
- App shell → Home UI: contains · Home and discovery screens
- App shell → Profile UI: contains · Profile viewing and editing screens
- App shell → Game UI: contains · Gameplay screens and state machine
- App shell → Waiting room: contains · Match lobby and waiting room
- App shell → Chat UI: contains · Chat interfaces
- App shell → Shared UI: contains · Reusable UI components
- Client utils → Gateway: calls · All client traffic is funneled through the gateway
- Gateway → Helpers: builds on · Shared routing and middleware plumbing
- Auth service → Helpers: builds on · Shared request-routing and repository utilities
- User service → Helpers: builds on · Shared request-routing and repository utilities
- Game service → Helpers: builds on · Shared request-routing and repository utilities
- Challenge svc → Helpers: builds on · Shared request-routing and repository utilities
- Chats service → Helpers: builds on · Shared request-routing and repository utilities
- Files service → Helpers: builds on · Shared request-routing and repository utilities
- User service → Event bus: publishes · User and presence updates fan out through events
- Challenge svc → Event bus: publishes · Challenge state changes are broadcast asynchronously
- Chats service → Event bus: publishes · Chat and room updates are broadcast asynchronously
- Game service → Event bus: publishes · Match events and side effects are broadcast asynchronously
- Gateway → Auth service: routes · Public auth traffic enters the auth service through the gateway
- Gateway → User service: routes · Profile and social traffic enters the user service through the gateway
- Gateway → Game service: routes · Gameplay traffic enters the game service through the gateway
- Gateway → Challenge svc: routes · Challenge traffic enters the challenge service through the gateway
- Gateway → Chats service: routes · Chat traffic enters the chats service through the gateway
- Gateway → Files service: routes · Static asset delivery is exposed through the gateway boundary
- Challenge svc → User service: uses · Challenge orchestration depends on user identity and presence
- Challenge svc → Game service: uses · Accepted challenges spawn or link to games
- Auth service → User service: coordinates · Identity flows coordinate with user data through service clients
