# ernwong/crystalorb architecture

> Architecture diagram of the GitHub repository ernwong/crystalorb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ernwong/crystalorb
- Repository: https://github.com/ernwong/crystalorb

## Overview

##### Main Components

- Core Library (Sequencer):
- Located in the /src directory, this is where the bulk of the networking logic exists. Key modules include protocol handling (client.rs and server.rs), time synchronization (clocksync.rs, timestamp.rs, fixed_timestepper.rs), and world simulation (modules under src/world).

- Integration Crates:
- Under /crates, two notable crates are present: “crystalorb-bevy-networking-turbulence” and “crystalorb-mock-network”.
- These provide concrete implementations or examples of integrating the core library with different networking layers (e.g., Bevy-based networking) and mock networking for testing.

- Examples:
- The /examples/demo and the standalone example (examples/standalone.rs) serve as templates and real-world usage scenarios that illustrate how the core library interacts with external components like a physics engine (Rapier, as mentioned in the README).
- These examples are useful to showcase the flow from client input to simulation and network synchronization.

- Testing Framework:
- The /tests directory shows various tests validating critical components like clock synchronization, state initialization, and determinism.
- Although not a runtime component, this directs you to consider how validation and isolation between components might be represented in the design.

##### Interactions and Data Flow

- Client-Server Interaction:
- From the /src files, particularly src/client.rs and src/server.rs, model the bidirectional flow.
- Clients apply local input immediately and then communicate with the server module, which runs the simulation authoritatively.

- Time and State Management:
- The clocksync and timestamp modules indicate a mechanism for aligning game simulation frames across clients and the server.

- Integration Points for Networking and Physics:
- Clearly the external dependencies where your own networking layer or a physics engine (e.g., Rapier via the demo) is plugged in.
- Use labels like “Networking Layer” and “Physics Engine” to emphasize that CrystalOrb acts as a mediator for these functionalities.

##### Architectural Choices and Patterns

- Modularity via Rust Workspaces:
- The multiple crates under /crates and /examples show a separation-of-concerns design where the core library is independent of implementation details.

- Sequencer Pattern:
- CrystalOrb works as a sequencer that synchronizes and sequences game states between predicted local states and authoritative server states.

- Use of Unstable Rust Features:
- Although not a runtime interaction, note that the project leverages advanced Rust features (e.g., generic associated types) which informs the design’s extensibility and performance characteristics.

##### Final Checklist

- Clearly delineate the main components:
- Client Module (input handling, prediction, interpolation)
- Server Module (authoritative simulation, reconciliation)
- Core Synchronization Logic (time, clocksync, fixed timestepper)
- World/Simulation Modules (state representation and update logic)
- Integration Points (crates for different networking layers, demos)
- Notes on external dependencies (networking layer, physics engine) as separate components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Subgraph
    subgraph "Core Library"
        SCL["Sequencer (src)"]:::core
        CM["Client Module (src/client.rs)"]:::core
        CStage["Client Stage (src/client/stage)"]:::core
        SM["Server Module (src/server.rs)"]:::core
        TS["Time & Sync (src/clocksync.rs, src/fixed_timestepper.rs, src/timestamp.rs)"]:::core
        TCS["Clock Sync (src/clocksync.rs)"]:::core
        FT["Fixed Timestepper (src/fixed_timestepper.rs)"]:::core
        TSmp["Timestamp (src/timestamp.rs)"]:::core
        WS["World/Simulation (src/world)"]:::core
        WDS["Display State (src/world/display_state.rs)"]:::core
        WSIM["Simulation (src/world/simulation.rs)"]:::core
        WT["World Trait (src/world/world_trait.rs)"]:::core
    end

    %% Relationships within Core Library
    SCL --> CM
    SCL --> SM
    SCL --> TS
    SCL --> WS
    CM --> CStage
    CM -->|"sends_input"| SM
    SM -->|"drives_simulation"| WS
    CM <-->|"snapshot"| SM
    CM -->|"sync_with"| TS
    TS -->|"updates"| WS
    TS --> TCS
    TS --> FT
    TS --> TSmp
    WS --> WDS
    WS --> WSIM
    WS --> WT

    %% Integration Adapters Subgraph
    subgraph "Integration Adapters"
        I1["Bevy Networking Adapter (crates/crystalorb-bevy-networking-turbulence)"]:::integration
        I2["Mock Networking Adapter (crates/crystalorb-mock-network)"]:::integration
    end
    I1 -.->|"integrates"| CM
    I1 -.->|"integrates"| SM
    I2 -.->|"integrates"| CM
    I2 -.->|"integrates"| SM

    %% Examples & Demos Subgraph
    subgraph "Examples & Demos"
        EX1["Demo Example (examples/demo)"]:::example
        EX2["Standalone Example (examples/standalone.rs)"]:::example
    end
    EX1 -->|"demonstrates"| CM
    EX1 -->|"demonstrates"| WS
    EX2 -->|"demonstrates"| CM

    %% Testing Framework Subgraph
    subgraph "Testing Framework"
        TST["Testing Framework (tests)"]:::example
        TCt["Test ClockSync (tests/clocksync.rs)"]:::example
        TDet["Test Determinism (tests/determinism.rs)"]:::example
        TSI["Test StateInit (tests/stateinit.rs)"]:::example
        TCm["Test Common (tests/common)"]:::example
    end
    TST --> TCt
    TST --> TDet
    TST --> TSI
    TST --> TCm
    TST -->|"validates"| TS
    TST -->|"validates"| WS
    TST -->|"validates"| CM

    %% Click Events for Core Library
    click SCL "https://github.com/ernwong/crystalorb/tree/master/src"
    click CM "https://github.com/ernwong/crystalorb/blob/master/src/client.rs"
    click CStage "https://github.com/ernwong/crystalorb/tree/master/src/client/stage"
    click SM "https://github.com/ernwong/crystalorb/blob/master/src/server.rs"
    click TCS "https://github.com/ernwong/crystalorb/blob/master/src/clocksync.rs"
    click FT "https://github.com/ernwong/crystalorb/blob/master/src/fixed_timestepper.rs"
    click TSmp "https://github.com/ernwong/crystalorb/blob/master/src/timestamp.rs"
    click WS "https://github.com/ernwong/crystalorb/tree/master/src/world"
    click WDS "https://github.com/ernwong/crystalorb/blob/master/src/world/display_state.rs"
    click WSIM "https://github.com/ernwong/crystalorb/blob/master/src/world/simulation.rs"
    click WT "https://github.com/ernwong/crystalorb/blob/master/src/world/world_trait.rs"

    %% Click Events for Integration Adapters
    click I1 "https://github.com/ernwong/crystalorb/tree/master/crates/crystalorb-bevy-networking-turbulence"
    click I2 "https://github.com/ernwong/crystalorb/tree/master/crates/crystalorb-mock-network"

    %% Click Events for Examples & Demos
    click EX1 "https://github.com/ernwong/crystalorb/tree/master/examples/demo"
    click EX2 "https://github.com/ernwong/crystalorb/blob/master/examples/standalone.rs"

    %% Click Events for Testing Framework
    click TST "https://github.com/ernwong/crystalorb/tree/master/tests"
    click TCt "https://github.com/ernwong/crystalorb/blob/master/tests/clocksync.rs"
    click TDet "https://github.com/ernwong/crystalorb/blob/master/tests/determinism.rs"
    click TSI "https://github.com/ernwong/crystalorb/blob/master/tests/stateinit.rs"
    click TCm "https://github.com/ernwong/crystalorb/tree/master/tests/common"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef integration fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef example fill:#FFA500,stroke:#000,stroke-width:1px;
```
