# parihsz/chrono architecture

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

- Interactive diagram: https://gitdiagram.com/parihsz/chrono
- Repository: https://github.com/parihsz/chrono

## Overview

Chrono is a Roblox library for custom physics replication and lag compensation. The principal workflow starts when a game calls Chrono.Start(), then uses client/server replication and interpolation to deliver entity state with a configurable delay. It also exposes historical snapshots and latency for lag compensation and debugging, and supports optimized server-controlled entity replication. The README documents these capabilities, but no runtime source was excerpted, so internal call paths are shown only as unverified relationships.

Main entry points: [`src/init.luau`](https://github.com/parihsz/chrono/blob/master/src/init.luau) (Chrono API), [`src/Server/Replicate.luau`](https://github.com/parihsz/chrono/blob/master/src/Server/Replicate.luau) (Server Replicator), [`src/Client/Replicate.luau`](https://github.com/parihsz/chrono/blob/master/src/Client/Replicate.luau) (Client Replicator), [`src/Client/InterpolationBuffer.luau`](https://github.com/parihsz/chrono/blob/master/src/Client/InterpolationBuffer.luau) (Interpolation Buffer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Library API"]
  node_chrono["Chrono API<br/>[init.luau]"]
end

subgraph group_client["Client Runtime"]
  node_client_clock["Client Clock<br/>[ClientClock.luau]"]
  node_client_receiver["Client Receiver<br/>[Receiver.luau]"]
  node_client_replicate["Client Replicator<br/>[Replicate.luau]"]
  node_interpolation["Interpolation Buffer"]
  node_model_resolver["Model Resolver<br/>[ModelResolver.luau]"]
end

subgraph group_server["Server Runtime"]
  node_server_clock["Server Clock<br/>[ServerClock.luau]"]
  node_server_receiver["Server Receiver<br/>[Receiver.luau]"]
  node_server_replicate["Server Replicator<br/>[Replicate.luau]"]
  node_entity_grid["Entity Grid<br/>[EntityGrid.luau]"]
end

subgraph group_shared["Shared Replication"]
  node_entity["Entity State<br/>[Entity.luau]"]
  node_rules["Replication Rules"]
  node_snapshots[("Historical Snapshots<br/>[Snapshots.luau]")]
  node_stats["Replication Stats<br/>[Stats.luau]"]
  node_events["Runtime Events<br/>[Events.luau]"]
end

node_developer(("Game Developer"))

node_developer -->|"calls Start"| node_chrono
node_chrono -.->|"starts runtime"| node_client_clock
node_chrono -.->|"starts runtime"| node_server_clock
node_client_receiver -.->|"delivers state"| node_client_replicate
node_client_replicate -.->|"buffers updates"| node_interpolation
node_interpolation -.->|"applies state"| node_model_resolver
node_server_receiver -.->|"delivers state"| node_server_replicate
node_server_replicate -.->|"replicates entities"| node_entity_grid
node_server_replicate -.->|"sends compressed data"| node_entity
node_rules -.->|"configures replication"| node_server_replicate
node_chrono -.->|"exposes history"| node_snapshots
node_chrono -.->|"exposes latency"| node_stats
node_snapshots -->|"supports lag compensation"| node_developer
node_stats -->|"supports debugging"| node_developer
node_events -.->|"signals runtime"| node_chrono

click node_chrono "https://github.com/parihsz/chrono/blob/master/src/init.luau"
click node_client_clock "https://github.com/parihsz/chrono/blob/master/src/Client/ClientClock.luau"
click node_client_receiver "https://github.com/parihsz/chrono/blob/master/src/Client/Receiver.luau"
click node_client_replicate "https://github.com/parihsz/chrono/blob/master/src/Client/Replicate.luau"
click node_interpolation "https://github.com/parihsz/chrono/blob/master/src/Client/InterpolationBuffer.luau"
click node_model_resolver "https://github.com/parihsz/chrono/blob/master/src/Client/ModelResolver.luau"
click node_server_clock "https://github.com/parihsz/chrono/blob/master/src/Server/ServerClock.luau"
click node_server_receiver "https://github.com/parihsz/chrono/blob/master/src/Server/Receiver.luau"
click node_server_replicate "https://github.com/parihsz/chrono/blob/master/src/Server/Replicate.luau"
click node_entity_grid "https://github.com/parihsz/chrono/blob/master/src/Server/EntityGrid.luau"
click node_entity "https://github.com/parihsz/chrono/blob/master/src/Shared/Entity.luau"
click node_rules "https://github.com/parihsz/chrono/blob/master/src/Shared/ReplicationRules.luau"
click node_snapshots "https://github.com/parihsz/chrono/blob/master/src/Shared/Snapshots.luau"
click node_stats "https://github.com/parihsz/chrono/blob/master/src/Shared/Stats.luau"
click node_events "https://github.com/parihsz/chrono/blob/master/src/Shared/Events.luau"

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_chrono toneBlue
class node_client_clock,node_client_receiver,node_client_replicate,node_interpolation,node_model_resolver toneAmber
class node_server_clock,node_server_receiver,node_server_replicate,node_entity_grid toneMint
class node_entity,node_rules,node_snapshots,node_stats,node_events toneRose
class node_developer toneIndigo
```

## Components

### Library API

- [Chrono API](https://github.com/parihsz/chrono/blob/master/src/init.luau): `src/init.luau`

### Client Runtime

- [Client Clock](https://github.com/parihsz/chrono/blob/master/src/Client/ClientClock.luau): `src/Client/ClientClock.luau`
- [Client Receiver](https://github.com/parihsz/chrono/blob/master/src/Client/Receiver.luau): `src/Client/Receiver.luau`
- [Client Replicator](https://github.com/parihsz/chrono/blob/master/src/Client/Replicate.luau): `src/Client/Replicate.luau`
- [Interpolation Buffer](https://github.com/parihsz/chrono/blob/master/src/Client/InterpolationBuffer.luau): `src/Client/InterpolationBuffer.luau`
- [Model Resolver](https://github.com/parihsz/chrono/blob/master/src/Client/ModelResolver.luau): `src/Client/ModelResolver.luau`

### Server Runtime

- [Server Clock](https://github.com/parihsz/chrono/blob/master/src/Server/ServerClock.luau): `src/Server/ServerClock.luau`
- [Server Receiver](https://github.com/parihsz/chrono/blob/master/src/Server/Receiver.luau): `src/Server/Receiver.luau`
- [Server Replicator](https://github.com/parihsz/chrono/blob/master/src/Server/Replicate.luau): `src/Server/Replicate.luau`
- [Entity Grid](https://github.com/parihsz/chrono/blob/master/src/Server/EntityGrid.luau): `src/Server/EntityGrid.luau`

### Shared Replication

- [Entity State](https://github.com/parihsz/chrono/blob/master/src/Shared/Entity.luau): `src/Shared/Entity.luau`
- [Replication Rules](https://github.com/parihsz/chrono/blob/master/src/Shared/ReplicationRules.luau): `src/Shared/ReplicationRules.luau`
- [Historical Snapshots](https://github.com/parihsz/chrono/blob/master/src/Shared/Snapshots.luau): `src/Shared/Snapshots.luau`
- [Replication Stats](https://github.com/parihsz/chrono/blob/master/src/Shared/Stats.luau): `src/Shared/Stats.luau`
- [Runtime Events](https://github.com/parihsz/chrono/blob/master/src/Shared/Events.luau): `src/Shared/Events.luau`

### Other components

- **Game Developer**

## Connections

- Game Developer → Chrono API: calls Start (evidence: `README.md`)
- Chrono API → Client Clock: starts runtime
- Chrono API → Server Clock: starts runtime
- Client Receiver → Client Replicator: delivers state
- Client Replicator → Interpolation Buffer: buffers updates
- Interpolation Buffer → Model Resolver: applies state
- Server Receiver → Server Replicator: delivers state
- Server Replicator → Entity Grid: replicates entities
- Server Replicator → Entity State: sends compressed data
- Replication Rules → Server Replicator: configures replication
- Chrono API → Historical Snapshots: exposes history
- Chrono API → Replication Stats: exposes latency
- Historical Snapshots → Game Developer: supports lag compensation (evidence: `README.md`)
- Replication Stats → Game Developer: supports debugging (evidence: `README.md`)
- Runtime Events → Chrono API: signals runtime
