# osomudeya/humour-game-playbook architecture

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

- Interactive diagram: https://gitdiagram.com/osomudeya/humour-game-playbook
- Repository: https://github.com/osomudeya/humour-game-playbook

## Overview

H-Game is a humor-themed memory game with a browser client and an Express API. The principal game workflow is session creation, card matching, and completion with scoring; the backend routes coordinate game data generation, validation, cached session state, and persistent records. Separate routes expose leaderboard and score/profile features, while metrics and tracing provide operational visibility. The README identifies the product but documents few implementation relationships; edges below rely on sampled code or the source index, with the browser-to-API link marked unverified.

Main entry points: [`backend/server.js`](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/server.js) (API server), [`backend/routes/game.js`](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/game.js) (Game sessions), [`backend/models/database.js`](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/models/database.js) (Game database access), [`backend/utils/redis.js`](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/utils/redis.js) (Cache utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game client"]
  node_browser["Browser game<br/>[game.js]"]
  node_clientlog["Client logger<br/>[logger.js]"]
end

subgraph group_api["Game API"]
  node_server["API server<br/>[server.js]"]
  node_validation["Request validation<br/>[validation.js]"]
  node_gameapi["Game sessions<br/>[game.js]"]
  node_gamedata["Game rules and content<br/>[gameData.js]"]
  node_scores["Scores and profiles<br/>[scores.js]"]
  node_leaderboard["Leaderboard<br/>[leaderboard.js]"]
end

subgraph group_state["Game state"]
  node_database["Game database access<br/>[database.js]"]
  node_cache["Cache utilities<br/>[redis.js]"]
end

subgraph group_ops["Observability"]
  node_backendlog["Backend logger<br/>[logger.js]"]
  node_metrics["Metrics middleware<br/>[metrics.js]"]
  node_tracing["Tracing setup<br/>[tracing.js]"]
end

node_player(("Player"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]
node_jaeger["Jaeger OTLP endpoint"]

node_player -->|"plays"| node_browser
node_browser -->|"logs via"| node_clientlog
node_browser -.->|"calls API"| node_server
node_server -->|"routes to"| node_gameapi
node_server -->|"routes to"| node_scores
node_server -->|"routes to"| node_leaderboard
node_server -.->|"uses"| node_validation
node_server -->|"initializes"| node_database
node_server -->|"initializes"| node_cache
node_server -->|"uses"| node_metrics
node_server -->|"logs with"| node_backendlog
node_server -->|"loads first"| node_tracing
node_gameapi -->|"validates with"| node_validation
node_gameapi -->|"generates from"| node_gamedata
node_gameapi -->|"reads and writes"| node_database
node_gameapi -->|"reads and writes"| node_cache
node_leaderboard -->|"queries"| node_database
node_leaderboard -->|"reads cache"| node_cache
node_database -->|"queries"| node_postgres
node_cache -->|"caches in"| node_redis
node_tracing -->|"exports traces"| node_jaeger

click node_browser "https://github.com/osomudeya/humour-game-playbook/blob/main/frontend/src/scripts/game.js"
click node_clientlog "https://github.com/osomudeya/humour-game-playbook/blob/main/frontend/src/utils/logger.js"
click node_server "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/server.js"
click node_validation "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/middleware/validation.js"
click node_gameapi "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/game.js"
click node_gamedata "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/utils/gameData.js"
click node_scores "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/scores.js"
click node_leaderboard "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/leaderboard.js"
click node_database "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/models/database.js"
click node_cache "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/utils/redis.js"
click node_backendlog "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/logger.js"
click node_metrics "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/middleware/metrics.js"
click node_tracing "https://github.com/osomudeya/humour-game-playbook/blob/main/backend/tracing.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_browser,node_clientlog toneBlue
class node_server,node_validation,node_gameapi,node_gamedata,node_scores,node_leaderboard,node_postgres,node_redis toneAmber
class node_database,node_cache toneMint
class node_backendlog,node_metrics,node_tracing toneRose
class node_player,node_jaeger toneIndigo
```

## Components

### Game client

- [Browser game](https://github.com/osomudeya/humour-game-playbook/blob/main/frontend/src/scripts/game.js): `frontend/src/scripts/game.js`
- [Client logger](https://github.com/osomudeya/humour-game-playbook/blob/main/frontend/src/utils/logger.js): `frontend/src/utils/logger.js`

### Game API

- [API server](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/server.js): `backend/server.js`
- [Request validation](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/middleware/validation.js): `backend/middleware/validation.js`
- [Game sessions](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/game.js): `backend/routes/game.js`
- [Game rules and content](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/utils/gameData.js): `backend/utils/gameData.js`
- [Scores and profiles](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/scores.js): `backend/routes/scores.js`
- [Leaderboard](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/routes/leaderboard.js): `backend/routes/leaderboard.js`

### Game state

- [Game database access](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/models/database.js): `backend/models/database.js`
- [Cache utilities](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/utils/redis.js): `backend/utils/redis.js`

### Observability

- [Backend logger](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/logger.js): `backend/logger.js`
- [Metrics middleware](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/middleware/metrics.js): `backend/middleware/metrics.js`
- [Tracing setup](https://github.com/osomudeya/humour-game-playbook/blob/main/backend/tracing.js): `backend/tracing.js`

### Other components

- **Player**
- **PostgreSQL**
- **Redis**
- **Jaeger OTLP endpoint**

## Connections

- Player → Browser game: plays
- Browser game → Client logger: logs via (evidence: `frontend/src/scripts/game.js`)
- Browser game → API server: calls API
- API server → Game sessions: routes to (evidence: `backend/server.js`)
- API server → Scores and profiles: routes to (evidence: `backend/server.js`)
- API server → Leaderboard: routes to (evidence: `backend/server.js`)
- API server → Request validation: uses
- API server → Game database access: initializes (evidence: `backend/server.js`)
- API server → Cache utilities: initializes (evidence: `backend/server.js`)
- API server → Metrics middleware: uses (evidence: `backend/server.js`)
- API server → Backend logger: logs with (evidence: `backend/server.js`)
- API server → Tracing setup: loads first (evidence: `backend/server.js`)
- Game sessions → Request validation: validates with (evidence: `backend/routes/game.js`)
- Game sessions → Game rules and content: generates from (evidence: `backend/routes/game.js`)
- Game sessions → Game database access: reads and writes (evidence: `backend/routes/game.js`)
- Game sessions → Cache utilities: reads and writes (evidence: `backend/routes/game.js`)
- Leaderboard → Game database access: queries (evidence: `backend/routes/leaderboard.js`)
- Leaderboard → Cache utilities: reads cache (evidence: `backend/routes/leaderboard.js`)
- Game database access → PostgreSQL: queries (evidence: `backend/models/database.js`)
- Cache utilities → Redis: caches in (evidence: `backend/utils/redis.js`)
- Tracing setup → Jaeger OTLP endpoint: exports traces (evidence: `backend/tracing.js`)