# mlange-42/ark architecture

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

- Interactive diagram: https://gitdiagram.com/mlange-42/ark
- Repository: https://github.com/mlange-42/ark

## Overview

##### Project type and purpose
- Project Type: An open-source Go library implementing an archetype-based Entity Component System (ECS).
- Purpose: Provide a high-performance, zero-dependency ECS framework for Go programs, with facilities for queries, events, relationships, batching, serialization, and code-generation helpers.

##### File structure
- Top-level directories:
- ecs – Core library code (world, entities, components, archetypes, queries, events, resources, relations, storage)
- ecs/internal/generate – Code-generation tool to emit optimized query/exchange/filter code from templates
- examples – Usage samples demonstrating integration with game engines (e.g., Pixel), custom events, parallel queries, relations
- benchmark – Performance benchmarks and profiling code
- docs – Hugo-based user guide and API docs
- Config/build/deploy files: .github workflows for tests, benchmarks, publish; .golangci.yml for linting; go.mod/go.sum

##### README for additional insights
- Highlights:
- Zero dependencies, 100% test coverage, benchmarks
- Features: archetype storage, entity relationships, event system, batch operations, serialization (via ark-serde)
- Tools: ark-serde, ark-tools, ark-pixel

a. Main components (logical layers)
- API Layer: ecs.NewWorld(), entity mappers, filters, queries, event emitters
- Core ECS Engine:
– World (registry of archetypes & tables)
– Archetype Manager (grouping of component sets)
– Tables & Pools (contiguous storage of component data)
– Component Columns (typed arrays)
– ID Map & Entity Index
- Query & Filter System (generates iterators over tables)
- Event & Observer Subsystem
- Resource & Relation Manager
- Code-Generation Tool (ecs/internal/generate)
- Benchmark Suite (benchmark/)
- Documentation Site (docs/)
b. Relationships and interactions
- World holds ArchetypeManager, TableStore, EntityRegistry
- Entity creation → World → Archetype → Table → Pools → Columns
- Query/Filter → World → matching Archetype Tables → returns typed component views
- Events → EventBus in World → Observers subscribe and receive callbacks
- Relations and Resources extend World’s storage and indexing
- Code-Gen tool reads templates + API definitions → emits optimized query & exchange code → built into ecs package
- Examples import ecs API; benchmarks import ecs to gauge performance
c. Architectural patterns & design principles
- Archetype-based storage for cache-friendly data locality
- Separation of concerns: storage vs query vs events vs relations
- Code-generation to avoid reflection and maximize performance
- Zero dependencies: minimal external integration
- Highly modular: each feature (batch, events, relations) is a distinct package area
d. Key technologies & frameworks
- Go modules (go.mod)
- Hugo for documentation site
- Go’s testing & benchmarking (testing package)
- GitHub Actions for CI/CD
- Code generation via Go templates

##### Detail
- Code-generation as part of the build pipeline, showing templates feeding into generated .go files
- CI workflows that run tests and benchmarks—optional but useful for a comprehensive view

## Diagram (Mermaid)

```mermaid
graph TB
    %% API Layer
    subgraph "API Layer"
        direction TB
        API["ecs/functions.go\n(config, constants, util)"]:::external
    end

    %% Core ECS Engine
    subgraph "Core ECS Engine" 
        direction TB
        World["World"]:::core
        ArchetypeMgr["Archetype Manager"]:::core
        TableStore["Table & Storage"]:::core
        Pool["Pool"]:::core
        Column["Component Column"]:::core
        IDMap["ID Map & Entity Index"]:::core
        Registry["Registry"]:::core
    end

    %% Query & Filter System
    subgraph "Query & Filter System"
        direction TB
        QuerySys["Query System"]:::core
        FilterSys["Filter System"]:::core
    end

    %% Event & Observer Subsystem
    subgraph "Event & Observer Subsystem"
        direction TB
        EventBus["Event Bus"]:::core
        Observer["Observer"]:::core
    end

    %% Resource & Relation Manager
    subgraph "Resource & Relation Manager"
        direction TB
        ResourceMgr["Resource Manager"]:::core
        RelationMgr["Relation Manager"]:::core
        Graph["Relation Graph"]:::core
    end

    %% Code-Generation Tool
    subgraph "Code-Generation Tool" 
        direction TB
        CodeGen["ecs/internal/generate"]:::tooling
    end

    %% Examples, Benchmark, Docs
    Examples["examples/"]:::docs
    Benchmark["benchmark/"]:::docs
    Docs["docs/"]:::docs

    %% Relationships
    API -->|"calls NewWorld() / utilities"| World
    World --> ArchetypeMgr
    ArchetypeMgr --> TableStore
    TableStore --> Pool
    Pool --> Column
    TableStore --> IDMap
    World --> Registry

    QuerySys -->|"queries"| World
    FilterSys -->|"filters"| World

    EventBus -->|"subscribe / emit"| Observer
    World --> EventBus

    ResourceMgr -->|"manages"| World
    RelationMgr -->|"manages"| Graph

    CodeGen -->|"generates code into"| World
    CodeGen --> QuerySys
    CodeGen --> FilterSys
    CodeGen --> Observer

    Examples -->|"import ecs API"| API
    Benchmark -->|"benchmarks ecs"| World
    Docs -->|"documentation site"| API

    %% Click Events Core ECS
    click World "https://github.com/mlange-42/ark/blob/main/ecs/world.go"
    click World "https://github.com/mlange-42/ark/blob/main/ecs/world_internal.go"
    click Registry "https://github.com/mlange-42/ark/blob/main/ecs/registry.go"
    click ArchetypeMgr "https://github.com/mlange-42/ark/blob/main/ecs/archetype.go"
    click TableStore "https://github.com/mlange-42/ark/blob/main/ecs/table.go"
    click TableStore "https://github.com/mlange-42/ark/blob/main/ecs/storage.go"
    click Pool "https://github.com/mlange-42/ark/blob/main/ecs/pool.go"
    click Column "https://github.com/mlange-42/ark/blob/main/ecs/column.go"
    click IDMap "https://github.com/mlange-42/ark/blob/main/ecs/id_map.go"

    %% Click Events Query & Filter
    click QuerySys "https://github.com/mlange-42/ark/blob/main/ecs/query.go"
    click QuerySys "https://github.com/mlange-42/ark/blob/main/ecs/query_gen.go"
    click QuerySys "https://github.com/mlange-42/ark/blob/main/ecs/query_nodebug.go"
    click QuerySys "https://github.com/mlange-42/ark/blob/main/ecs/query_debug.go"
    click FilterSys "https://github.com/mlange-42/ark/blob/main/ecs/filter.go"
    click FilterSys "https://github.com/mlange-42/ark/blob/main/ecs/filter_gen.go"

    %% Click Events Event Subsystem
    click EventBus "https://github.com/mlange-42/ark/blob/main/ecs/events.go"
    click Observer "https://github.com/mlange-42/ark/blob/main/ecs/observer.go"
    click Observer "https://github.com/mlange-42/ark/blob/main/ecs/observers_gen.go"

    %% Click Events Resource & Relation
    click ResourceMgr "https://github.com/mlange-42/ark/blob/main/ecs/resource.go"
    click ResourceMgr "https://github.com/mlange-42/ark/blob/main/ecs/resources.go"
    click RelationMgr "https://github.com/mlange-42/ark/blob/main/ecs/relation.go"
    click Graph "https://github.com/mlange-42/ark/blob/main/ecs/graph.go"

    %% Click Events API Layer
    click API "https://github.com/mlange-42/ark/blob/main/ecs/functions.go"
    click API "https://github.com/mlange-42/ark/blob/main/ecs/config.go"
    click API "https://github.com/mlange-42/ark/blob/main/ecs/constants.go"
    click API "https://github.com/mlange-42/ark/blob/main/ecs/util.go"

    %% Click Events Code-Gen Tool
    click CodeGen "https://github.com/mlange-42/ark/tree/main/ecs/internal/generate/"

    %% Click Events Examples, Benchmark, Docs
    click Examples "https://github.com/mlange-42/ark/tree/main/examples/"
    click Benchmark "https://github.com/mlange-42/ark/tree/main/benchmark/"
    click Docs "https://github.com/mlange-42/ark/tree/main/docs/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef tooling fill:#E6FFEA,stroke:#28A745,stroke-width:1px
    classDef docs fill:#F1F1F1,stroke:#6A737D,stroke-width:1px
    classDef external fill:#FFEBD0,stroke:#D15704,stroke-width:1px
```
