# mfreeman451/dd-chatgpt-dm architecture

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

- Interactive diagram: https://gitdiagram.com/mfreeman451/dd-chatgpt-dm
- Repository: https://github.com/mfreeman451/dd-chatgpt-dm

## Overview

This repository is an early D&D game backend with a Nuxt character-management frontend, gRPC/Connect interfaces, persistent player/room state, and command/event scaffolding. The intended user workflow is character creation, game login or setup, then room navigation and command execution, with state retained server-side. The README also describes a DM/chat system and generated room art, but those integrations are goals rather than implemented components in the sampled evidence. Some subsystem paths are based on the tree and README; their internal wiring is not shown.

Main entry points: [`server/internal/game/room.go`](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/game/room.go) (Room navigation), [`proto`](https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/proto) (RPC schemas), [`server/internal/service/service.go`](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/service/service.go) (Game service), [`server/pkg/db`](https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/server/pkg/db) (Database adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web character app"]
  node_webui["Character UI"]
  node_webapi["Web API"]
  node_webtypes["Web RPC clients<br/>[game.client.ts]"]
  node_webproto["Web protobuf<br/>[game.ts]"]
end

subgraph group_api["RPC and service"]
  node_rpcproto["RPC schemas"]
  node_gamerpc["Game RPC<br/>[game.connect.go]"]
  node_playerrpc["Player RPC<br/>[player.connect.go]"]
  node_roomrpc["Room RPC<br/>[room.connect.go]"]
  node_service["Game service<br/>[service.go]"]
  node_server["Connect server<br/>[server.go]"]
  node_cli["CLI client<br/>[main.go]"]
  node_clientlogin["Login helper<br/>[client.go]"]
end

subgraph group_state["Game state"]
  node_playerstate["Player state<br/>[player.go]"]
  node_roomstate["Room navigation<br/>[room.go]"]
  node_database[("Database adapters")]
  node_redis[("Redis cache<br/>[redis.go]")]
end

subgraph group_events["Events and operations"]
  node_cqrs["CQRS wiring<br/>[cqrs.go]"]
  node_handlers["Command handlers<br/>[handlers.go]"]
  node_janitor["Janitor<br/>[janitor.go]"]
end

node_player(("Player"))
node_chat(("DM chat"))
node_art(("Generated room art"))

node_player -->|"creates character"| node_webui
node_webui -.->|"submits character"| node_webapi
node_webapi -.->|"calls RPC"| node_webtypes
node_webtypes -->|"uses messages"| node_webproto
node_webproto -->|"defines contract"| node_rpcproto
node_cli -->|"calls game RPC"| node_gamerpc
node_cli -->|"delegates login"| node_clientlogin
node_clientlogin -->|"returns placeholder token"| node_player
node_gamerpc -->|"implements schema"| node_rpcproto
node_playerrpc -->|"implements schema"| node_rpcproto
node_roomrpc -->|"implements schema"| node_rpcproto
node_service -->|"reads and writes"| node_database
node_service -->|"receives client"| node_redis
node_service -->|"publishes messages"| node_cqrs
node_database -.->|"stores player data"| node_playerstate
node_database -.->|"stores room data"| node_roomstate
node_cqrs -->|"registers handlers"| node_handlers
node_janitor -->|"subscribes events"| node_handlers
node_chat -.->|"describes new rooms"| node_roomstate
node_chat -.->|"saves descriptions"| node_roomstate
node_roomstate -.->|"inspires image"| node_art

click node_webui "https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/web/pages"
click node_webapi "https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/web/server/api"
click node_webtypes "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/web/pb/game.client.ts"
click node_webproto "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/web/pb/game.ts"
click node_rpcproto "https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/proto"
click node_gamerpc "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/gen/game/v1/gamev1connect/game.connect.go"
click node_playerrpc "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/gen/player/v1/playerv1connect/player.connect.go"
click node_roomrpc "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/gen/room/v1/roomv1connect/room.connect.go"
click node_service "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/service/service.go"
click node_server "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/server/server.go"
click node_cli "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/client/main.go"
click node_clientlogin "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/client/pkg/client/client.go"
click node_playerstate "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/game/player.go"
click node_roomstate "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/game/room.go"
click node_database "https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/server/pkg/db"
click node_redis "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/pkg/db/cache/redis.go"
click node_cqrs "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/pkg/watermill/cqrs.go"
click node_handlers "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/pkg/watermill/handlers.go"
click node_janitor "https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/janitor/janitor.go"

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_webui,node_webapi,node_webtypes,node_webproto toneBlue
class node_rpcproto,node_gamerpc,node_playerrpc,node_roomrpc,node_service,node_server,node_cli,node_clientlogin toneAmber
class node_playerstate,node_roomstate,node_database,node_redis toneMint
class node_cqrs,node_handlers,node_janitor toneRose
class node_player,node_chat,node_art toneIndigo
```

## Components

### Web character app

- [Character UI](https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/web/pages): `web/pages`
- [Web API](https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/web/server/api): `web/server/api`
- [Web RPC clients](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/web/pb/game.client.ts): `web/pb/game.client.ts`
- [Web protobuf](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/web/pb/game.ts): `web/pb/game.ts`

### RPC and service

- [RPC schemas](https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/proto): `proto`
- [Game RPC](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/gen/game/v1/gamev1connect/game.connect.go): `gen/game/v1/gamev1connect/game.connect.go`
- [Player RPC](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/gen/player/v1/playerv1connect/player.connect.go): `gen/player/v1/playerv1connect/player.connect.go`
- [Room RPC](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/gen/room/v1/roomv1connect/room.connect.go): `gen/room/v1/roomv1connect/room.connect.go`
- [Game service](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/service/service.go): `server/internal/service/service.go`
- [Connect server](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/server/server.go): `server/internal/server/server.go`
- [CLI client](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/client/main.go): `client/main.go`
- [Login helper](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/client/pkg/client/client.go): `client/pkg/client/client.go`

### Game state

- [Player state](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/game/player.go): `server/internal/game/player.go`
- [Room navigation](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/game/room.go): `server/internal/game/room.go`
- [Database adapters](https://github.com/mfreeman451/dd-chatgpt-dm/tree/main/server/pkg/db): `server/pkg/db`
- [Redis cache](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/pkg/db/cache/redis.go): `server/pkg/db/cache/redis.go`

### Events and operations

- [CQRS wiring](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/pkg/watermill/cqrs.go): `server/pkg/watermill/cqrs.go`
- [Command handlers](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/pkg/watermill/handlers.go): `server/pkg/watermill/handlers.go`
- [Janitor](https://github.com/mfreeman451/dd-chatgpt-dm/blob/main/server/internal/janitor/janitor.go): `server/internal/janitor/janitor.go`

### Other components

- **Player**
- **DM chat**
- **Generated room art**

## Connections

- Player → Character UI: creates character
- Character UI → Web API: submits character
- Web API → Web RPC clients: calls RPC
- Web RPC clients → Web protobuf: uses messages (evidence: `web/pb/game.client.ts`)
- Web protobuf → RPC schemas: defines contract (evidence: `web/pb/game.ts`)
- CLI client → Game RPC: calls game RPC (evidence: `client/main.go`)
- CLI client → Login helper: delegates login (evidence: `client/main.go`)
- Login helper → Player: returns placeholder token (evidence: `client/pkg/client/client.go`)
- Game RPC → RPC schemas: implements schema (evidence: `gen/game/v1/gamev1connect/game.connect.go`)
- Player RPC → RPC schemas: implements schema (evidence: `gen/player/v1/playerv1connect/player.connect.go`)
- Room RPC → RPC schemas: implements schema (evidence: `gen/room/v1/roomv1connect/room.connect.go`)
- Game service → Database adapters: reads and writes (evidence: `server/internal/service/service.go`)
- Game service → Redis cache: receives client
- Game service → CQRS wiring: publishes messages (evidence: `server/internal/service/service.go`)
- Database adapters → Player state: stores player data
- Database adapters → Room navigation: stores room data
- CQRS wiring → Command handlers: registers handlers
- Janitor → Command handlers: subscribes events
- DM chat → Room navigation: describes new rooms
- DM chat → Room navigation: saves descriptions
- Room navigation → Generated room art: inspires image
