# oteryn/oteryn-game architecture

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

- Interactive diagram: https://gitdiagram.com/oteryn/oteryn-game
- Repository: https://github.com/oteryn/oteryn-game

## Overview

Oteryn is a native Rust multiplayer game: a player uses the native client to enter and play in an authoritative, multichannel game world. The principal runtime path spans client interaction, gameplay transport and admission, server-side gameplay, and durable state. The client tree also documents substantial UI and feature areas, while the repository README establishes the protocol, authoritative-server, and PostgreSQL architecture. The excerpts do not expose most client wiring or server domain internals, so those links are shown as unverified rather than asserted calls.

Main entry points: [`crates/gameplay/dispatch/src/gameplay_transport/connection.rs`](https://github.com/oteryn/oteryn-game/blob/main/crates/gameplay/dispatch/src/gameplay_transport/connection.rs) (Gameplay connection), [`apps/client/src/bevy_shell`](https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/bevy_shell) (Bevy shell), [`crates/gameplay/dispatch/src`](https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/dispatch/src) (Gameplay dispatch), [`crates/gameplay`](https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay) (Gameplay domains)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Native client"]
  node_client_entry["Client entry"]
  node_shell["Bevy shell"]
  node_game_ui["Gameplay UI"]
  node_feature_modules["Gameplay features"]
  node_client_play["Play runtime"]
end

subgraph group_transport["Gameplay transport"]
  node_game_connection["Gameplay connection<br/>[connection.rs]"]
  node_capabilities["Capability negotiation<br/>[capabilities.rs]"]
  node_protocol["Game protocol"]
end

subgraph group_server["Game server"]
  node_server_entry["Server entry<br/>[main.rs]"]
  node_dispatch["Gameplay dispatch"]
  node_gameplay_domains["Gameplay domains"]
  node_session["Session services"]
end

subgraph group_persistence["Durable state"]
  node_postgres[("PostgreSQL")]
  node_durability["Durability services"]
end

subgraph group_content["World and content"]
  node_content_model["Native content"]
  node_world_tools["World and content tooling"]
end

node_player(("Player"))

node_player -.->|"launches"| node_client_entry
node_client_entry -.->|"starts"| node_shell
node_shell -.->|"presents"| node_game_ui
node_shell -.->|"hosts"| node_feature_modules
node_feature_modules -.->|"uses"| node_client_play
node_client_play -.->|"exchanges gameplay"| node_game_connection
node_game_connection -->|"uses"| node_protocol
node_game_connection -->|"negotiates"| node_capabilities
node_game_connection -->|"delegates admission"| node_session
node_game_connection -.->|"dispatches gameplay"| node_dispatch
node_server_entry -.->|"serves gameplay"| node_dispatch
node_dispatch -.->|"invokes"| node_gameplay_domains
node_gameplay_domains -.->|"persists state"| node_durability
node_durability -.->|"reads and writes"| node_postgres
node_world_tools -.->|"authors content"| node_content_model
node_content_model -.->|"supplies world data"| node_gameplay_domains

click node_client_entry "https://github.com/oteryn/oteryn-game/blob/main/apps/client/src/bin/oteryn-client-bevy.rs"
click node_shell "https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/bevy_shell"
click node_game_ui "https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/bevy_shell/game_ui"
click node_feature_modules "https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/features"
click node_client_play "https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/play"
click node_game_connection "https://github.com/oteryn/oteryn-game/blob/main/crates/gameplay/dispatch/src/gameplay_transport/connection.rs"
click node_capabilities "https://github.com/oteryn/oteryn-game/blob/main/crates/gameplay/dispatch/src/gameplay_transport/capabilities.rs"
click node_protocol "https://github.com/oteryn/oteryn-game/tree/main/crates/protocol-oteryn"
click node_server_entry "https://github.com/oteryn/oteryn-game/blob/main/apps/game-server/src/main.rs"
click node_dispatch "https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/dispatch/src"
click node_gameplay_domains "https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay"
click node_session "https://github.com/oteryn/oteryn-game/tree/main/crates/session"
click node_durability "https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/durability"
click node_content_model "https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/content/src/content"
click node_world_tools "https://github.com/oteryn/oteryn-game/tree/main/tools/content-schema"

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_entry,node_shell,node_game_ui,node_feature_modules,node_client_play toneBlue
class node_game_connection,node_capabilities,node_protocol toneAmber
class node_server_entry,node_dispatch,node_gameplay_domains,node_session toneMint
class node_postgres,node_durability toneRose
class node_content_model,node_world_tools,node_player toneIndigo
```

## Components

### Native client

- [Client entry](https://github.com/oteryn/oteryn-game/blob/main/apps/client/src/bin/oteryn-client-bevy.rs): `apps/client/src/bin/oteryn-client-bevy.rs`
- [Bevy shell](https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/bevy_shell): `apps/client/src/bevy_shell`
- [Gameplay UI](https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/bevy_shell/game_ui): `apps/client/src/bevy_shell/game_ui`
- [Gameplay features](https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/features): `apps/client/src/features`
- [Play runtime](https://github.com/oteryn/oteryn-game/tree/main/apps/client/src/play): `apps/client/src/play`

### Gameplay transport

- [Gameplay connection](https://github.com/oteryn/oteryn-game/blob/main/crates/gameplay/dispatch/src/gameplay_transport/connection.rs): `crates/gameplay/dispatch/src/gameplay_transport/connection.rs`
- [Capability negotiation](https://github.com/oteryn/oteryn-game/blob/main/crates/gameplay/dispatch/src/gameplay_transport/capabilities.rs): `crates/gameplay/dispatch/src/gameplay_transport/capabilities.rs`
- [Game protocol](https://github.com/oteryn/oteryn-game/tree/main/crates/protocol-oteryn): `crates/protocol-oteryn`

### Game server

- [Server entry](https://github.com/oteryn/oteryn-game/blob/main/apps/game-server/src/main.rs): `apps/game-server/src/main.rs`
- [Gameplay dispatch](https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/dispatch/src): `crates/gameplay/dispatch/src`
- [Gameplay domains](https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay): `crates/gameplay`
- [Session services](https://github.com/oteryn/oteryn-game/tree/main/crates/session): `crates/session`

### Durable state

- **PostgreSQL**
- [Durability services](https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/durability): `crates/gameplay/durability`

### World and content

- [Native content](https://github.com/oteryn/oteryn-game/tree/main/crates/gameplay/content/src/content): `crates/gameplay/content/src/content`
- [World and content tooling](https://github.com/oteryn/oteryn-game/tree/main/tools/content-schema): `tools/content-schema`

### Other components

- **Player**

## Connections

- Player → Client entry: launches
- Client entry → Bevy shell: starts
- Bevy shell → Gameplay UI: presents
- Bevy shell → Gameplay features: hosts
- Gameplay features → Play runtime: uses (evidence: `apps/client/src/features/0152-item-forge/controller.rs`)
- Play runtime → Gameplay connection: exchanges gameplay
- Gameplay connection → Game protocol: uses (evidence: `crates/gameplay/dispatch/src/gameplay_transport/connection.rs`)
- Gameplay connection → Capability negotiation: negotiates (evidence: `crates/gameplay/dispatch/src/gameplay_transport/capabilities.rs`)
- Gameplay connection → Session services: delegates admission (evidence: `crates/gameplay/dispatch/src/gameplay_transport/connection.rs`)
- Gameplay connection → Gameplay dispatch: dispatches gameplay (evidence: `crates/gameplay/dispatch/src/gameplay_transport/connection.rs`)
- Server entry → Gameplay dispatch: serves gameplay
- Gameplay dispatch → Gameplay domains: invokes (evidence: `crates/gameplay/dispatch/src/gameplay_transport/postgres_tests/support/questpc8_retrieval_routes_fixtures.rs`)
- Gameplay domains → Durability services: persists state
- Durability services → PostgreSQL: reads and writes
- World and content tooling → Native content: authors content
- Native content → Gameplay domains: supplies world data
