How barbateam/fishes-vs-crabeez works
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: services Shared services · app-routing.module.ts Routes · child Child flow · api HTTP APIs
Components 18
Frontend
Angular client with role-based flows and shared UI/services.
- App shell · Top-level client application shell and module wiring.
frontend/src/app - Routes · Client route structure and top-level navigation boundaries.
frontend/src/app/app-routing.module.ts - Home flow · Initial selection and entry screens.
frontend/src/app/home - Child flow · Child-facing gameplay, profile, and game session screens.
frontend/src/app/child - Ergo flow · Adult/caregiver management and configuration screens.
frontend/src/app/ergo - Shared UI · Reusable visual components shared across client flows.
frontend/src/app/shared/components - Shared services · API-facing services, socket client, local storage, and notifications.
frontend/src/app/shared/services - Assets · 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 · REST-style modules for game info, users, results, and leaderboards.
backend/app/api - Game runner · Starts and coordinates live gameplay sessions.
backend/app/game-runner - Socket layer · Role-based socket clients and real-time communication helpers.
backend/app/sockets - Game runtime · Receives player actions and emits game updates during a session.
backend/app/game-ts/runtime - Game model · Core simulation rules, events, enemies, quiz logic, and log accumulation.
backend/app/game-ts/model - Stats pipeline · Transforms raw outcomes into player results and learner statistics.
backend/app/stats - Shared contracts · Schemas, tables, enums, mocks, and utilities shared across backend modules.
backend/app/shared - Database · Persistence boundary for profiles, results, statistics, and related data.
backend/database
Prototype
Separate Python-based UI mockup kept outside production runtime.
- Maquette · Earlier Python-based UI prototype, separate from the shipped app.
maquette/src
Deploy
Container and compose setup for running the stack.
- Compose stack · Container orchestration for frontend, backend, and e2e environments.
ops/docker-compose.yml
Connections 26
- 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.