# kurobeats/ashfall architecture

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

- Interactive diagram: https://gitdiagram.com/kurobeats/ashfall
- Repository: https://github.com/kurobeats/ashfall

## Overview

Ashfall is a server-authoritative co-op mod for Fallout 3 and New Vegas. Players connect through the desktop client, authenticate with a dedicated server, and synchronize game state; the client relays engine commands and events through an injected bridge. The server also supports master-server listings, imported game data, combat and world simulation, persistence, and WASM game modes. The graph combines README-documented product flows with sampled module references; some runtime wiring is documented but its implementation files were not sampled, so those relationships cite the README.

Main entry points: [`crates/ashfall-client/src/game.rs`](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/game.rs) (Client session), [`crates/ashfall-server/src/network.rs`](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/network.rs) (Server networking), [`crates/ashfall-server/src/dispatch.rs`](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/dispatch.rs) (Packet dispatch), [`crates/ashfall-bridge/src/network.rs`](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge/src/network.rs) (Bridge pipe server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Player client"]
  node_client_ui["Client UI<br/>[app.rs]"]
  node_client_game["Client session<br/>[game.rs]"]
  node_client_network["Client networking<br/>[network.rs]"]
  node_client_sync["State sync<br/>[sync.rs]"]
  node_client_world["Client world view<br/>[registry.rs]"]
  node_client_ipc["Engine IPC<br/>[mod.rs]"]
end

subgraph group_server["Authoritative services"]
  node_master[("Server browser master<br/>[server_list.rs]")]
  node_server_network["Server networking<br/>[network.rs]"]
  node_server_dispatch["Packet dispatch<br/>[dispatch.rs]"]
  node_auth["Authentication<br/>[auth.rs]"]
  node_session["Player sessions<br/>[session.rs]"]
  node_handlers["Gameplay handlers"]
  node_world["World simulation"]
  node_combat["Combat resolution<br/>[resolver.rs]"]
  node_database[("Game database")]
  node_esm["Mod importer<br/>[esm_import.rs]"]
  node_scripts["WASM game modes<br/>[engine.rs]"]
end

subgraph group_bridge["Game integration"]
  node_bridge_proxy["Injected DLL proxy<br/>[lib.rs]"]
  node_bridge_network["Bridge pipe server<br/>[network.rs]"]
  node_commands["Engine commands<br/>[commands.rs]"]
  node_hooks["Engine hooks"]
end

subgraph group_shared["Shared protocol"]
  node_protocol["Game protocol<br/>[mod.rs]"]
end

node_player(("Player"))

node_player -->|"uses"| node_client_ui
node_client_ui -->|"connects"| node_client_game
node_client_game -->|"sends packets"| node_client_network
node_client_network -->|"exchanges UDP"| node_server_network
node_server_network -.->|"dispatches packets"| node_server_dispatch
node_server_dispatch -.->|"routes auth"| node_auth
node_auth -->|"creates session"| node_session
node_server_dispatch -.->|"routes gameplay"| node_handlers
node_handlers -.->|"updates state"| node_world
node_handlers -.->|"resolves combat"| node_combat
node_world -.->|"persists world"| node_database
node_esm -->|"imports records"| node_database
node_server_dispatch -.->|"dispatches events"| node_scripts
node_client_game -->|"synchronizes state"| node_client_sync
node_client_sync -.->|"updates view"| node_client_world
node_client_game -->|"polls bridge"| node_client_ipc
node_client_ipc -->|"sends TCP"| node_bridge_network
node_bridge_proxy -.->|"hosts in-game"| node_bridge_network
node_bridge_network -->|"dispatches commands"| node_commands
node_commands -->|"calls engine hooks"| node_hooks
node_hooks -->|"reports events"| node_bridge_network
node_client_network -.->|"encodes messages"| node_protocol
node_server_network -.->|"encodes messages"| node_protocol
node_master -->|"lists servers"| node_client_ui
node_server_network -.->|"publishes listing"| node_master

click node_client_ui "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/ui/app.rs"
click node_client_game "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/game.rs"
click node_client_network "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/network.rs"
click node_client_sync "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/sync.rs"
click node_client_world "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/world/registry.rs"
click node_client_ipc "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/ipc/mod.rs"
click node_master "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-master/src/server_list.rs"
click node_server_network "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/network.rs"
click node_server_dispatch "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/dispatch.rs"
click node_auth "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/handlers/auth.rs"
click node_session "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/session.rs"
click node_handlers "https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-server/src/handlers"
click node_world "https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-server/src/world"
click node_combat "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/combat/resolver.rs"
click node_database "https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-server/src/db"
click node_esm "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/db/esm_import.rs"
click node_scripts "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/script/engine.rs"
click node_bridge_proxy "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge-proxy/src/lib.rs"
click node_bridge_network "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge/src/network.rs"
click node_commands "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge/src/commands.rs"
click node_hooks "https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-bridge/src/hooks"
click node_protocol "https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-core/src/protocol/mod.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_ui,node_client_game,node_client_network,node_client_sync,node_client_world,node_client_ipc toneBlue
class node_master,node_server_network,node_server_dispatch,node_auth,node_session,node_handlers,node_world,node_combat,node_database,node_esm,node_scripts toneAmber
class node_bridge_proxy,node_bridge_network,node_commands,node_hooks toneMint
class node_protocol toneRose
class node_player toneIndigo
```

## Components

### Player client

- [Client UI](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/ui/app.rs): `crates/ashfall-client/src/ui/app.rs`
- [Client session](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/game.rs): `crates/ashfall-client/src/game.rs`
- [Client networking](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/network.rs): `crates/ashfall-client/src/network.rs`
- [State sync](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/sync.rs): `crates/ashfall-client/src/sync.rs`
- [Client world view](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/world/registry.rs): `crates/ashfall-client/src/world/registry.rs`
- [Engine IPC](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-client/src/ipc/mod.rs): `crates/ashfall-client/src/ipc/mod.rs`

### Authoritative services

- [Server browser master](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-master/src/server_list.rs): `crates/ashfall-master/src/server_list.rs`
- [Server networking](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/network.rs): `crates/ashfall-server/src/network.rs`
- [Packet dispatch](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/dispatch.rs): `crates/ashfall-server/src/dispatch.rs`
- [Authentication](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/handlers/auth.rs): `crates/ashfall-server/src/handlers/auth.rs`
- [Player sessions](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/session.rs): `crates/ashfall-server/src/session.rs`
- [Gameplay handlers](https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-server/src/handlers): `crates/ashfall-server/src/handlers`
- [World simulation](https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-server/src/world): `crates/ashfall-server/src/world`
- [Combat resolution](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/combat/resolver.rs): `crates/ashfall-server/src/combat/resolver.rs`
- [Game database](https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-server/src/db): `crates/ashfall-server/src/db`
- [Mod importer](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/db/esm_import.rs): `crates/ashfall-server/src/db/esm_import.rs`
- [WASM game modes](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-server/src/script/engine.rs): `crates/ashfall-server/src/script/engine.rs`

### Game integration

- [Injected DLL proxy](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge-proxy/src/lib.rs): `crates/ashfall-bridge-proxy/src/lib.rs`
- [Bridge pipe server](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge/src/network.rs): `crates/ashfall-bridge/src/network.rs`
- [Engine commands](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-bridge/src/commands.rs): `crates/ashfall-bridge/src/commands.rs`
- [Engine hooks](https://github.com/kurobeats/ashfall/tree/main/crates/ashfall-bridge/src/hooks): `crates/ashfall-bridge/src/hooks`

### Shared protocol

- [Game protocol](https://github.com/kurobeats/ashfall/blob/main/crates/ashfall-core/src/protocol/mod.rs): `crates/ashfall-core/src/protocol/mod.rs`

### Other components

- **Player**

## Connections

- Player → Client UI: uses (evidence: `README.md`)
- Client UI → Client session: connects (evidence: `crates/ashfall-client/src/ui/app.rs`)
- Client session → Client networking: sends packets (evidence: `crates/ashfall-client/src/game.rs`)
- Client networking → Server networking: exchanges UDP (evidence: `README.md`)
- Server networking → Packet dispatch: dispatches packets
- Packet dispatch → Authentication: routes auth
- Authentication → Player sessions: creates session (evidence: `crates/ashfall-server/src/handlers/auth.rs`)
- Packet dispatch → Gameplay handlers: routes gameplay
- Gameplay handlers → World simulation: updates state
- Gameplay handlers → Combat resolution: resolves combat
- World simulation → Game database: persists world
- Mod importer → Game database: imports records (evidence: `crates/ashfall-server/src/db/esm_import.rs`)
- Packet dispatch → WASM game modes: dispatches events
- Client session → State sync: synchronizes state (evidence: `crates/ashfall-client/src/game.rs`)
- State sync → Client world view: updates view
- Client session → Engine IPC: polls bridge (evidence: `crates/ashfall-client/src/game.rs`)
- Engine IPC → Bridge pipe server: sends TCP (evidence: `README.md`)
- Injected DLL proxy → Bridge pipe server: hosts in-game (evidence: `README.md`)
- Bridge pipe server → Engine commands: dispatches commands (evidence: `crates/ashfall-bridge/src/network.rs`)
- Engine commands → Engine hooks: calls engine hooks (evidence: `crates/ashfall-bridge/src/commands.rs`)
- Engine hooks → Bridge pipe server: reports events (evidence: `crates/ashfall-bridge/src/hooks/mod.rs`)
- Client networking → Game protocol: encodes messages
- Server networking → Game protocol: encodes messages
- Server browser master → Client UI: lists servers (evidence: `README.md`)
- Server networking → Server browser master: publishes listing (evidence: `README.md`)
