# piratejl/archetype-ecs-lib architecture

> Architecture diagram of the GitHub repository piratejl/archetype-ecs-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piratejl/archetype-ecs-lib
- Repository: https://github.com/piratejl/archetype-ecs-lib

## Overview

Archetype ECS Lib is a small TypeScript runtime for managing entities and component data, querying that data, and running game systems. An application creates a World, adds systems, and advances it with World.update or a multiphase Schedule. Systems can query entities, access singleton resources, emit events, and queue structural changes for safe flushing. World snapshots and profiling are additional capabilities. The tree and excerpts establish these major modules, but do not expose every internal call, so uncertain wiring is omitted.

Main entry points: [`src/ecs/World.ts`](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/World.ts) (World), [`src/ecs/Schedule.ts`](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Schedule.ts) (Schedule), [`src/ecs/Commands.ts`](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Commands.ts) (Deferred Commands), [`src/ecs/Events.ts`](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Events.ts) (Event Channels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["World API"]
  node_world["World<br/>[World.ts]"]
  node_resources[("World Resources<br/>[World.ts]")]
  node_exports["Public Exports<br/>[index.ts]"]
end

subgraph group_storage["Entity Storage"]
  node_archetype[("Archetype Tables<br/>[Archetype.ts]")]
  node_entities[("Entity Manager<br/>[EntityManager.ts]")]
  node_signature["Signatures<br/>[Signature.ts]"]
  node_registry["Type Registry<br/>[TypeRegistry.ts]"]
end

subgraph group_execution["Systems and Services"]
  node_schedule["Schedule<br/>[Schedule.ts]"]
  node_commands["Deferred Commands<br/>[Commands.ts]"]
  node_events["Event Channels<br/>[Events.ts]"]
end

subgraph group_support["Snapshots and Profiling"]
  node_snapshot["Snapshot Store"]
  node_stats["Stats Overlay<br/>[StatsOverlay.ts]"]
end

node_app(("Game Application"))
node_systems["Systems"]

node_app -->|"imports"| node_exports
node_app -->|"creates"| node_world
node_app -->|"configures"| node_schedule
node_schedule -->|"runs"| node_systems
node_schedule -->|"runs phases on"| node_world
node_systems -->|"queries and accesses"| node_world
node_systems -->|"queues changes"| node_commands
node_systems -->|"uses"| node_events
node_world -->|"allocates entities"| node_entities
node_world -->|"stores and queries"| node_archetype
node_world -->|"matches signatures"| node_signature
node_world -->|"resolves types"| node_registry
node_world -->|"reads and writes"| node_resources
node_world -->|"flushes"| node_commands
node_world -->|"manages channels"| node_events
node_world -->|"saves and restores"| node_snapshot
node_world -->|"profiles frames"| node_stats

click node_world "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/World.ts"
click node_schedule "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Schedule.ts"
click node_commands "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Commands.ts"
click node_events "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Events.ts"
click node_archetype "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Archetype.ts"
click node_entities "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/EntityManager.ts"
click node_signature "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Signature.ts"
click node_registry "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/TypeRegistry.ts"
click node_resources "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/World.ts"
click node_snapshot "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/WorldSnapshotStore.ts"
click node_stats "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/stats/StatsOverlay.ts"
click node_exports "https://github.com/piratejl/archetype-ecs-lib/blob/master/src/index.ts"

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_world,node_resources,node_exports toneBlue
class node_archetype,node_entities,node_signature,node_registry toneAmber
class node_schedule,node_commands,node_events toneMint
class node_snapshot,node_stats toneRose
class node_app,node_systems toneIndigo
```

## Components

### World API

- [World](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/World.ts): `src/ecs/World.ts`
- [World Resources](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/World.ts): `src/ecs/World.ts`
- [Public Exports](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/index.ts): `src/index.ts`

### Entity Storage

- [Archetype Tables](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Archetype.ts): `src/ecs/Archetype.ts`
- [Entity Manager](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/EntityManager.ts): `src/ecs/EntityManager.ts`
- [Signatures](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Signature.ts): `src/ecs/Signature.ts`
- [Type Registry](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/TypeRegistry.ts): `src/ecs/TypeRegistry.ts`

### Systems and Services

- [Schedule](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Schedule.ts): `src/ecs/Schedule.ts`
- [Deferred Commands](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Commands.ts): `src/ecs/Commands.ts`
- [Event Channels](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/Events.ts): `src/ecs/Events.ts`

### Snapshots and Profiling

- [Snapshot Store](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/WorldSnapshotStore.ts): `src/ecs/WorldSnapshotStore.ts`
- [Stats Overlay](https://github.com/piratejl/archetype-ecs-lib/blob/master/src/ecs/stats/StatsOverlay.ts): `src/ecs/stats/StatsOverlay.ts`

### Other components

- **Game Application**
- **Systems**

## Connections

- Game Application → Public Exports: imports
- Game Application → World: creates
- Game Application → Schedule: configures
- Schedule → Systems: runs
- Schedule → World: runs phases on
- Systems → World: queries and accesses
- Systems → Deferred Commands: queues changes
- Systems → Event Channels: uses
- World → Entity Manager: allocates entities
- World → Archetype Tables: stores and queries
- World → Signatures: matches signatures
- World → Type Registry: resolves types
- World → World Resources: reads and writes
- World → Deferred Commands: flushes
- World → Event Channels: manages channels
- World → Snapshot Store: saves and restores
- World → Stats Overlay: profiles frames