# barbateam/fishes-vs-crabeez architecture

> Architecture diagram of the GitHub repository barbateam/fishes-vs-crabeez, 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/barbateam/fishes-vs-crabeez
- Repository: https://github.com/barbateam/fishes-vs-crabeez

## Overview

1. **Repository shape**
   This is a monorepo for a browser game, with three main product areas:
   - `frontend/`: the production Angular client
   - `backend/`: the Node.js server and game logic
   - `maquette/`: an earlier UI prototype, kept separately from the shipped app

2. **Overall architecture**
   The game is split into a **real-time gameplay path** and a **data/service path**:
   - gameplay uses sockets and an in-memory game engine
   - player/profile/statistics/leaderboard data use API-style backend modules
   The frontend consumes both through Angular services.

3. **Frontend boundary**
   `frontend/` is an Angular application organized by user role and flow:
   - `home/` for initial choice/selection screens
   - `child/` for child-facing gameplay and profile screens
   - `ergo/` for adult/caregiver management screens
   Shared UI lives under `src/app/shared/components`, and shared API-facing services live under `src/app/shared/services`.

4. **Frontend runtime and communication**
   The frontend talks to the backend through:
   - `socket.service.ts` for live game sessions
   - REST-oriented services such as `games.service.ts`, `leaderboard.service.ts`, `user.service.ts`, and statistics/results services
   The client also has route guards for access control and deactivation protection during active sessions.

5. **Backend boundary**
   `backend/app/` is the server-side application. Its major responsibilities are:
   - exposing HTTP APIs under `app/api/`
   - managing game sessions under `app/game-runner/`
   - hosting the game engine/domain model under `app/game/` and `app/game-ts/`
   - providing shared data definitions under `app/shared/`
   - supporting real-time socket clients under `app/sockets/`

6. **Game session flow**
   The real-time gameplay loop is centered on:
   - `game-runner/` starting and coordinating a session
   - `game/runtime/` receiving player actions and emitting game updates
   - `game/model/` or `game-ts/model/` containing the actual simulation rules
   This is the boundary where keyboard/motion input, enemy spawning, quiz events, and player state updates are processed.

7. **Game domain model**
   The game model is fairly rich and self-contained:
   - `game-engine/` contains core simulation concepts like player, projectile, lane, difficulty, variables, and enemy types
   - `events-handler/` models player and game events such as frenzy, paralysis, waves, and boss waves
   - `quiz-handler/` handles question generation and answer checking
   - `game-log-accumulator.ts` suggests session logs are collected for post-game analysis or results

8. **Backend data APIs**
   The backend API modules are split by domain:
   - `game-info`
   - `game-leaderboard`
   - `global-leaderboard`
   - `player-results`
   - `player-statistics`
   - `users`
   Each API has a `manager.js` layer, which likely contains business logic and persistence coordination, while `index.js` exposes the route/module entry point.

9. **Shared backend contracts**
   `backend/app/shared/` holds cross-cutting definitions used across APIs and stats generation:
   - validation schemas in `schemas/`
   - table/persistence abstractions in `tables/`
   - enums and types in `types/`
   - deterministic test data in `mocks/`
   This indicates a clear contract layer between business logic and storage/validation.

10. **Statistics and derived views**
   `backend/app/stats/` builds higher-level player statistics and result summaries from raw game outcomes.
   The presence of builders and utilities like `grade.js` and `mistakes-sorter.js` suggests the backend transforms session data into learner-facing progress metrics, not just raw scores.

11. **Socket/client roles**
   `backend/app/sockets/app-client/roles/` defines multiple client roles such as child, ergo, game-master, guest, and player.
   This implies role-based real-time behavior, where the same socket infrastructure can serve gameplay, administration, and guest/session control flows.

12. **Storage and deployment**
   The `backend/database/` directory exists as a persistence boundary, though the exact DB technology is not exposed in the tree.  
   Deployment is containerized via:
   - `backend/Dockerfile.backend`
   - `frontend/Dockerfile.frontend`
   - `ops/docker-compose.yml` and `ops/docker-compose-e2e.yml`
   So the system is designed to run as separate frontend/backend services, with a dedicated e2e stack.

13. **Prototype and assets**
   `maquette/` is a separate Python-based mockup/prototype, not part of the production runtime.  
   `frontend/src/assets/` contains the game’s visual/audio content, which is a meaningful part of the frontend because the child-facing gameplay relies heavily on local assets for the game experience.

14. **Architecture diagram takeaway**
   An accurate diagram should show:
   - Angular frontend split by user role
   - backend split into HTTP APIs, real-time game runtime, and shared domain/data modules
   - a live socket channel for gameplay
   - REST/data services for progress, users, and leaderboards
   - a persistence layer for profiles, results, and stats
   - a separate prototype/maquette path and a containerized deployment layer

Main entry points: [`frontend/src/app/shared/services`](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/shared/services) (Shared services), [`frontend/src/app/app-routing.module.ts`](https://github.com/barbateam/fishes-vs-crabeez/blob/main/frontend/src/app/app-routing.module.ts) (Routes), [`frontend/src/app/child`](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/child) (Child flow), [`backend/app/api`](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/api) (HTTP APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>Angular app"]
  node_frontend_routes["Routes<br/>routing"]
  node_frontend_home["Home flow<br/>role flow"]
  node_frontend_child["Child flow<br/>player UI"]
  node_frontend_ergo["Ergo flow<br/>caregiver UI"]
  node_frontend_shared_ui["Shared UI<br/>components"]
  node_frontend_shared_svcs["Shared services<br/>client services"]
  node_frontend_assets["Assets<br/>media bundle"]
end

subgraph group_backend["Backend"]
  node_backend_api["HTTP APIs<br/>api layer"]
  node_backend_runner["Game runner<br/>session coordinator"]
  node_backend_socket["Socket layer<br/>realtime gateway"]
  node_backend_runtime["Game runtime<br/>session runtime"]
  node_backend_game["Game model<br/>simulation domain"]
  node_backend_stats["Stats pipeline<br/>derived data"]
  node_backend_shared["Shared contracts<br/>schemas/tables/types"]
  node_backend_db[("Database<br/>persistence boundary")]
end

subgraph group_prototype["Prototype"]
  node_prototype_ui["Maquette<br/>prototype UI"]
end

subgraph group_deploy["Deploy"]
  node_deploy_stack["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"defines"| node_frontend_routes
node_frontend_routes -->|"routes"| node_frontend_home
node_frontend_routes -->|"routes"| node_frontend_child
node_frontend_routes -->|"routes"| node_frontend_ergo
node_frontend_home -->|"uses"| node_frontend_shared_ui
node_frontend_child -->|"uses"| node_frontend_shared_ui
node_frontend_ergo -->|"uses"| node_frontend_shared_ui
node_frontend_home -->|"calls"| node_frontend_shared_svcs
node_frontend_child -->|"calls"| node_frontend_shared_svcs
node_frontend_ergo -->|"calls"| node_frontend_shared_svcs
node_frontend_shared_svcs -->|"REST"| node_backend_api
node_frontend_shared_svcs -->|"socket"| node_backend_socket
node_frontend_child -->|"loads"| node_frontend_assets
node_backend_api -->|"contracts"| node_backend_shared
node_backend_api -->|"persists"| node_backend_db
node_backend_runner -->|"coordinates"| node_backend_socket
node_backend_runner -->|"drives"| node_backend_runtime
node_backend_runtime -->|"simulates"| node_backend_game
node_backend_game -->|"uses"| node_backend_shared
node_backend_stats -->|"reads/writes"| node_backend_db
node_backend_stats -->|"contracts"| node_backend_shared
node_backend_socket -->|"streams"| node_backend_runtime
node_prototype_ui -->|"influences"| node_frontend_app
node_deploy_stack -->|"runs"| node_frontend_app
node_deploy_stack -->|"runs"| node_backend_api
node_deploy_stack -->|"runs"| node_backend_socket

click node_frontend_app "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app"
click node_frontend_routes "https://github.com/barbateam/fishes-vs-crabeez/blob/main/frontend/src/app/app-routing.module.ts"
click node_frontend_home "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/home"
click node_frontend_child "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/child"
click node_frontend_ergo "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/ergo"
click node_frontend_shared_ui "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/shared/components"
click node_frontend_shared_svcs "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/shared/services"
click node_frontend_assets "https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/assets"
click node_backend_api "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/api"
click node_backend_runner "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/game-runner"
click node_backend_socket "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/sockets"
click node_backend_runtime "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/game-ts/runtime"
click node_backend_game "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/game-ts/model"
click node_backend_stats "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/stats"
click node_backend_shared "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/shared"
click node_backend_db "https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/database"
click node_prototype_ui "https://github.com/barbateam/fishes-vs-crabeez/tree/main/maquette/src"
click node_deploy_stack "https://github.com/barbateam/fishes-vs-crabeez/blob/main/ops/docker-compose.yml"

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_routes,node_frontend_home,node_frontend_child,node_frontend_ergo,node_frontend_shared_ui,node_frontend_shared_svcs,node_frontend_assets toneBlue
class node_backend_api,node_backend_runner,node_backend_socket,node_backend_runtime,node_backend_game,node_backend_stats,node_backend_shared,node_backend_db toneAmber
class node_prototype_ui toneMint
class node_deploy_stack toneRose
```

## Components

### Frontend

Angular client with role-based flows and shared UI/services.

- [App shell](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app): Angular app · Top-level client application shell and module wiring. · `frontend/src/app`
- [Routes](https://github.com/barbateam/fishes-vs-crabeez/blob/main/frontend/src/app/app-routing.module.ts): routing · Client route structure and top-level navigation boundaries. · `frontend/src/app/app-routing.module.ts`
- [Home flow](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/home): role flow · Initial selection and entry screens. · `frontend/src/app/home`
- [Child flow](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/child): player UI · Child-facing gameplay, profile, and game session screens. · `frontend/src/app/child`
- [Ergo flow](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/ergo): caregiver UI · Adult/caregiver management and configuration screens. · `frontend/src/app/ergo`
- [Shared UI](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/shared/components): components · Reusable visual components shared across client flows. · `frontend/src/app/shared/components`
- [Shared services](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/app/shared/services): client services · API-facing services, socket client, local storage, and notifications. · `frontend/src/app/shared/services`
- [Assets](https://github.com/barbateam/fishes-vs-crabeez/tree/main/frontend/src/assets): media bundle · Game art, audio, and other local client assets. · `frontend/src/assets`

### Backend

Node server with APIs, real-time gameplay, shared contracts, and stats.

- [HTTP APIs](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/api): api layer · REST-style modules for game info, users, results, and leaderboards. · `backend/app/api`
- [Game runner](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/game-runner): session coordinator · Starts and coordinates live gameplay sessions. · `backend/app/game-runner`
- [Socket layer](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/sockets): realtime gateway · Role-based socket clients and real-time communication helpers. · `backend/app/sockets`
- [Game runtime](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/game-ts/runtime): session runtime · Receives player actions and emits game updates during a session. · `backend/app/game-ts/runtime`
- [Game model](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/game-ts/model): simulation domain · Core simulation rules, events, enemies, quiz logic, and log accumulation. · `backend/app/game-ts/model`
- [Stats pipeline](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/stats): derived data · Transforms raw outcomes into player results and learner statistics. · `backend/app/stats`
- [Shared contracts](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/app/shared): schemas/tables/types · Schemas, tables, enums, mocks, and utilities shared across backend modules. · `backend/app/shared`
- [Database](https://github.com/barbateam/fishes-vs-crabeez/tree/main/backend/database): persistence boundary · Persistence boundary for profiles, results, statistics, and related data. · `backend/database`

### Prototype

Separate Python-based UI mockup kept outside production runtime.

- [Maquette](https://github.com/barbateam/fishes-vs-crabeez/tree/main/maquette/src): prototype UI · Earlier Python-based UI prototype, separate from the shipped app. · `maquette/src`

### Deploy

Container and compose setup for running the stack.

- [Compose stack](https://github.com/barbateam/fishes-vs-crabeez/blob/main/ops/docker-compose.yml): deployment · Container orchestration for frontend, backend, and e2e environments. · `ops/docker-compose.yml`

## Connections

- App shell → Routes: defines · App shell wires the client route tree.
- Routes → Home flow: routes · Entry and selection screens live in the home flow.
- Routes → Child flow: routes · Child-facing gameplay and profile flow.
- Routes → Ergo flow: routes · Caregiver management flow.
- Home flow → Shared UI: uses · Home screens reuse shared components.
- Child flow → Shared UI: uses · Child screens reuse shared components.
- Ergo flow → Shared UI: uses · Ergo screens reuse shared components.
- Home flow → Shared services: calls · Home flow consumes client services.
- Child flow → Shared services: calls · Child flow consumes API and socket services.
- Ergo flow → Shared services: calls · Ergo flow consumes API-facing services.
- Shared services → HTTP APIs: REST · Client service layer talks to backend HTTP APIs.
- Shared services → Socket layer: socket · Live gameplay uses the socket channel.
- Child flow → Assets: loads · Gameplay and feedback depend on local media assets.
- HTTP APIs → Shared contracts: contracts · API modules rely on shared schemas, tables, and types.
- HTTP APIs → Database: persists · API business logic ultimately stores domain data.
- Game runner → Socket layer: coordinates · Session coordination is exposed through sockets.
- Game runner → Game runtime: drives · Runner hands control to the live session runtime.
- Game runtime → Game model: simulates · Runtime executes the actual game model rules.
- Game model → Shared contracts: uses · Game model shares enums and schemas with the rest of the backend.
- Stats pipeline → Database: reads/writes · Statistics and results are derived from persisted outcomes.
- Stats pipeline → Shared contracts: contracts · Derived views use the same shared definitions.
- Socket layer → Game runtime: streams · Socket clients exchange player actions and game updates with runtime.
- Maquette → App shell: influences · Prototype UI is a separate lineage from the shipped Angular app.
- Compose stack → App shell: runs · Compose stack deploys the client service.
- Compose stack → HTTP APIs: runs · Compose stack deploys the server service.
- Compose stack → Socket layer: runs · Compose stack includes the real-time backend.
