# ak47andrew/fableforge-reborn architecture

> Architecture diagram of the GitHub repository ak47andrew/fableforge-reborn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ak47andrew/fableforge-reborn
- Repository: https://github.com/ak47andrew/fableforge-reborn

## Overview

#### Purpose and Workspace Layout
FableForge Reborn is a Rust virtual-tabletop project organized as a Cargo workspace with three crates:
- Shared protocol/domain crate: `common/src/lib.rs`
- Interactive client application: `client/src/main.rs`
- Authoritative multiplayer server: `server/src/main.rs`

The README provides product intent but no operational instructions; architecture must be inferred from crate and module boundaries.

#### Client Application Entry and Composition
`client/src/main.rs` is the client entry point and composes UI, configuration, authentication/token handling, camera behavior, and network connectivity. The client is structured as a native application rather than a browser-oriented frontend.

Core client modules:
- `client/src/button.rs` — UI button/component behavior.
- `client/src/smart_camera.rs` — tabletop viewport/camera control.
- `client/src/config.rs` and `client/src/consts.rs` — client configuration and shared client constants.

#### Client-to-Server Boundary
The network boundary is explicitly isolated in `client/src/websocket.rs`. This module is the likely transport adapter between the client’s UI/state interactions and server-side multiplayer state.

Authentication/session credential concerns are separated into `client/src/token.rs`, indicating tokens are managed on the client independently of presentation and WebSocket transport. The expected control flow is: startup loads configuration/token state, establishes a WebSocket connection, then forwards user actions and receives synchronized game/tabletop updates.

#### Server Runtime and State Authority
`server/src/main.rs` is the server process entry point. It owns service startup and connection handling, while `server/src/state.rs` isolates server-managed application state.

This establishes the server as the authority boundary for shared tabletop/session data:
- Connection requests enter through `server/src/main.rs`.
- Shared or per-session state is read and mutated through `server/src/state.rs`.
- Updates are returned to connected clients through the network layer.

No persistence, HTTP API, database integration, or deployment infrastructure is visible in the supplied tree.

#### Shared Contract Crate
`common/src/lib.rs` is the workspace’s cross-process contract boundary. It should contain protocol messages, common domain types, and serialization-compatible structures used by both `client` and `server`.

The intended dependency direction is:
- `client` → `common`
- `server` → `common`
- no direct client-to-server source dependency

Keeping multiplayer message and domain definitions here prevents transport payload drift between independently compiled binaries.

#### Primary Flow
1. The client starts at `client/src/main.rs`, initializes local configuration and UI/camera state.
2. Credential/token logic from `client/src/token.rs` supports session identity or authorization.
3. `client/src/websocket.rs` connects to the server and exchanges types defined in `common/src/lib.rs`.
4. `server/src/main.rs` accepts/processes client traffic and delegates authoritative mutations to `server/src/state.rs`.
5. The server broadcasts or returns state changes; the client maps them into tabletop UI and camera-visible state.

#### Material Runtime and External Dependencies
The implementation is Rust/Cargo-based, with workspace dependency definitions in `Cargo.toml`, `client/Cargo.toml`, `server/Cargo.toml`, and `common/Cargo.toml`. A WebSocket service is architecturally central; its concrete library, host configuration, authentication scheme, rendering runtime, and storage backend are not identifiable from the provided files.

Main entry points: [`client/src/websocket.rs`](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/websocket.rs) (WebSocket adapter), [`client/src/main.rs`](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/main.rs) (Client startup), [`server/src/main.rs`](https://github.com/ak47andrew/fableforge-reborn/blob/master/server/src/main.rs) (Server runtime), [`client/src/button.rs`](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/button.rs) (Tabletop UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Native Client"]
  node_client_main["Client startup<br/>Rust binary<br/>[main.rs]"]
  node_client_ui["Tabletop UI<br/>UI component<br/>[button.rs]"]
  node_client_camera["Smart camera<br/>viewport control<br/>[smart_camera.rs]"]
  node_client_config["Client config<br/>configuration<br/>[config.rs]"]
  node_client_constants["Client constants<br/>[consts.rs]"]
  node_client_token["Token handling<br/>session credentials<br/>[token.rs]"]
  node_client_ws{{"WebSocket adapter<br/>transport<br/>[websocket.rs]"}}
end

subgraph group_server["Authoritative Server"]
  node_server_main["Server runtime<br/>Rust binary<br/>[main.rs]"]
  node_server_state[("Authoritative state<br/>shared state<br/>[state.rs]")]
end

node_common_contract["Shared contract<br/>Rust library<br/>[lib.rs]"]

node_client_main -->|"initializes"| node_client_ui
node_client_main -->|"initializes"| node_client_camera
node_client_main -->|"loads"| node_client_config
node_client_main -->|"uses"| node_client_constants
node_client_main -->|"loads"| node_client_token
node_client_main -->|"connects through"| node_client_ws
node_client_ui -->|"forwards actions"| node_client_ws
node_client_ws -->|"applies updates"| node_client_ui
node_client_ws -->|"syncs visible state"| node_client_camera
node_client_ws -->|"uses credentials"| node_client_token
node_client_ws -->|"uses messages"| node_common_contract
node_server_main -->|"uses messages"| node_common_contract
node_client_ws -->|"WebSocket traffic"| node_server_main
node_server_main -->|"delegates mutations"| node_server_state
node_server_state -->|"state updates"| node_server_main
node_server_main -->|"broadcasts updates"| node_client_ws

click node_common_contract "https://github.com/ak47andrew/fableforge-reborn/blob/master/common/src/lib.rs"
click node_client_main "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/main.rs"
click node_client_ui "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/button.rs"
click node_client_camera "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/smart_camera.rs"
click node_client_config "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/config.rs"
click node_client_constants "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/consts.rs"
click node_client_token "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/token.rs"
click node_client_ws "https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/websocket.rs"
click node_server_main "https://github.com/ak47andrew/fableforge-reborn/blob/master/server/src/main.rs"
click node_server_state "https://github.com/ak47andrew/fableforge-reborn/blob/master/server/src/state.rs"

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_client_main,node_client_ui,node_client_camera,node_client_config,node_client_constants,node_client_token,node_client_ws toneBlue
class node_server_main,node_server_state toneAmber
class node_common_contract toneNeutral
```

## Components

### Native Client

Interactive tabletop application.

- [Client startup](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/main.rs): Rust binary · Composes local application services. · `client/src/main.rs`
- [Tabletop UI](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/button.rs): UI component · `client/src/button.rs`
- [Smart camera](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/smart_camera.rs): viewport control · `client/src/smart_camera.rs`
- [Client config](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/config.rs): configuration · `client/src/config.rs`
- [Client constants](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/consts.rs): constants · `client/src/consts.rs`
- [Token handling](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/token.rs): session credentials · Manages client-side identity or authorization tokens. · `client/src/token.rs`
- [WebSocket adapter](https://github.com/ak47andrew/fableforge-reborn/blob/master/client/src/websocket.rs): transport · Exchanges multiplayer messages with the server. · `client/src/websocket.rs`

### Authoritative Server

Multiplayer runtime and shared-state authority.

- [Server runtime](https://github.com/ak47andrew/fableforge-reborn/blob/master/server/src/main.rs): Rust binary · Accepts connections and processes client traffic. · `server/src/main.rs`
- [Authoritative state](https://github.com/ak47andrew/fableforge-reborn/blob/master/server/src/state.rs): shared state · Reads and mutates tabletop or session state. · `server/src/state.rs`

### Other components

- [Shared contract](https://github.com/ak47andrew/fableforge-reborn/blob/master/common/src/lib.rs): Rust library · Protocol messages and shared domain types. · `common/src/lib.rs`

## Connections

- Client startup → Tabletop UI: initializes
- Client startup → Smart camera: initializes
- Client startup → Client config: loads
- Client startup → Client constants: uses
- Client startup → Token handling: loads
- Client startup → WebSocket adapter: connects through
- Tabletop UI → WebSocket adapter: forwards actions
- WebSocket adapter → Tabletop UI: applies updates
- WebSocket adapter → Smart camera: syncs visible state
- WebSocket adapter → Token handling: uses credentials
- WebSocket adapter → Shared contract: uses messages
- Server runtime → Shared contract: uses messages
- WebSocket adapter → Server runtime: WebSocket traffic
- Server runtime → Authoritative state: delegates mutations
- Authoritative state → Server runtime: state updates
- Server runtime → WebSocket adapter: broadcasts updates