# sandermertens/flecs architecture

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

- Interactive diagram: https://gitdiagram.com/sandermertens/flecs
- Repository: https://github.com/sandermertens/flecs

## Overview

Flecs is a C/C++ Entity Component System framework for games and simulations. The main workflow is to create a world, register entities and components, define queries and systems, then progress the world so a pipeline schedules matching systems to process component data. The graph also shows documented capabilities such as prefabs, reflection and JSON, scripting, monitoring, and REST access. Core paths and selected addon sources support the relationships shown; several addon links reflect README or API documentation rather than sampled implementation, so uncertain wiring is omitted.

Main entry points: [`src/world.c`](https://github.com/sandermertens/flecs/blob/master/src/world.c) (ECS world), [`src/addons/app.c`](https://github.com/sandermertens/flecs/blob/master/src/addons/app.c) (Application loop), [`src/entity.c`](https://github.com/sandermertens/flecs/blob/master/src/entity.c) (Entities and IDs), [`src/query/engine/eval.c`](https://github.com/sandermertens/flecs/blob/master/src/query/engine/eval.c) (Query engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["World and storage"]
  node_world["ECS world<br/>[world.c]"]
  node_entities["Entities and IDs<br/>[entity.c]"]
  node_archetype_storage[("Archetype storage<br/>[table.c]")]
  node_sparse_storage[("Sparse components<br/>[sparse_storage.c]")]
end

subgraph group_execution["Queries and execution"]
  node_query_api["Query API<br/>[api.c]"]
  node_query_compile["Query compiler<br/>[compiler.c]"]
  node_query_cache[("Query cache<br/>[cache.c]")]
  node_query_engine["Query engine<br/>[eval.c]"]
  node_systems["Systems<br/>[system.c]"]
  node_pipeline["Pipeline scheduler<br/>[pipeline.c]"]
end

subgraph group_addons["Runtime addons"]
  node_app["Application loop<br/>[app.c]"]
  node_prefabs["Prefabs and hierarchy<br/>[prefab.c]"]
  node_reflection["Reflection and metadata<br/>[meta.c]"]
  node_json["JSON serialization<br/>[json.c]"]
  node_scripting["Script runtime<br/>[script.c]"]
  node_stats["Statistics monitoring<br/>[stats.c]"]
  node_rest["REST interface<br/>[rest.c]"]
end

subgraph group_interfaces["Language interfaces"]
  node_c_api["C API<br/>[flecs.h]"]
  node_cpp_api["C++ API<br/>[world.hpp]"]
end

node_developer(("Application developer"))

node_developer -->|"uses"| node_c_api
node_developer -->|"uses"| node_cpp_api
node_c_api -->|"creates and configures"| node_world
node_cpp_api -->|"wraps"| node_world
node_world -->|"manages"| node_entities
node_entities -->|"stores component sets"| node_archetype_storage
node_entities -->|"stores sparse data"| node_sparse_storage
node_query_api -->|"compiles terms"| node_query_compile
node_query_api -->|"maintains matches"| node_query_cache
node_query_engine -->|"iterates matches"| node_query_cache
node_query_engine -->|"matches tables"| node_archetype_storage
node_query_engine -->|"evaluates sparse data"| node_sparse_storage
node_systems -->|"uses queries"| node_query_api
node_pipeline -->|"schedules systems"| node_systems
node_app -->|"progresses"| node_world
node_app -->|"runs via progress"| node_pipeline
node_systems -->|"processes component data"| node_archetype_storage
node_prefabs -->|"instantiates entities"| node_entities
node_reflection -->|"provides type metadata"| node_json
node_json -->|"serializes world data"| node_world
node_scripting -.->|"evaluates against"| node_world
node_app -.->|"can enable"| node_rest
node_app -.->|"can enable"| node_stats
node_stats -.->|"monitors"| node_pipeline

click node_c_api "https://github.com/sandermertens/flecs/blob/master/include/flecs.h"
click node_cpp_api "https://github.com/sandermertens/flecs/blob/master/include/flecs/addons/cpp/world.hpp"
click node_world "https://github.com/sandermertens/flecs/blob/master/src/world.c"
click node_entities "https://github.com/sandermertens/flecs/blob/master/src/entity.c"
click node_archetype_storage "https://github.com/sandermertens/flecs/blob/master/src/storage/table.c"
click node_sparse_storage "https://github.com/sandermertens/flecs/blob/master/src/storage/sparse_storage.c"
click node_query_api "https://github.com/sandermertens/flecs/blob/master/src/query/api.c"
click node_query_compile "https://github.com/sandermertens/flecs/blob/master/src/query/compiler/compiler.c"
click node_query_cache "https://github.com/sandermertens/flecs/blob/master/src/query/cache/cache.c"
click node_query_engine "https://github.com/sandermertens/flecs/blob/master/src/query/engine/eval.c"
click node_systems "https://github.com/sandermertens/flecs/blob/master/src/addons/system/system.c"
click node_pipeline "https://github.com/sandermertens/flecs/blob/master/src/addons/pipeline/pipeline.c"
click node_app "https://github.com/sandermertens/flecs/blob/master/src/addons/app.c"
click node_prefabs "https://github.com/sandermertens/flecs/blob/master/src/addons/prefab/prefab.c"
click node_reflection "https://github.com/sandermertens/flecs/blob/master/src/addons/meta/meta.c"
click node_json "https://github.com/sandermertens/flecs/blob/master/src/addons/json/json.c"
click node_scripting "https://github.com/sandermertens/flecs/blob/master/src/addons/script/script.c"
click node_stats "https://github.com/sandermertens/flecs/blob/master/src/addons/stats/stats.c"
click node_rest "https://github.com/sandermertens/flecs/blob/master/src/addons/rest.c"

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_entities,node_archetype_storage,node_sparse_storage toneBlue
class node_query_api,node_query_compile,node_query_cache,node_query_engine,node_systems,node_pipeline toneAmber
class node_app,node_prefabs,node_reflection,node_json,node_scripting,node_stats,node_rest toneMint
class node_c_api,node_cpp_api toneRose
class node_developer toneIndigo
```

## Components

### World and storage

- [ECS world](https://github.com/sandermertens/flecs/blob/master/src/world.c): `src/world.c`
- [Entities and IDs](https://github.com/sandermertens/flecs/blob/master/src/entity.c): `src/entity.c`
- [Archetype storage](https://github.com/sandermertens/flecs/blob/master/src/storage/table.c): `src/storage/table.c`
- [Sparse components](https://github.com/sandermertens/flecs/blob/master/src/storage/sparse_storage.c): `src/storage/sparse_storage.c`

### Queries and execution

- [Query API](https://github.com/sandermertens/flecs/blob/master/src/query/api.c): `src/query/api.c`
- [Query compiler](https://github.com/sandermertens/flecs/blob/master/src/query/compiler/compiler.c): `src/query/compiler/compiler.c`
- [Query cache](https://github.com/sandermertens/flecs/blob/master/src/query/cache/cache.c): `src/query/cache/cache.c`
- [Query engine](https://github.com/sandermertens/flecs/blob/master/src/query/engine/eval.c): `src/query/engine/eval.c`
- [Systems](https://github.com/sandermertens/flecs/blob/master/src/addons/system/system.c): `src/addons/system/system.c`
- [Pipeline scheduler](https://github.com/sandermertens/flecs/blob/master/src/addons/pipeline/pipeline.c): `src/addons/pipeline/pipeline.c`

### Runtime addons

- [Application loop](https://github.com/sandermertens/flecs/blob/master/src/addons/app.c): `src/addons/app.c`
- [Prefabs and hierarchy](https://github.com/sandermertens/flecs/blob/master/src/addons/prefab/prefab.c): `src/addons/prefab/prefab.c`
- [Reflection and metadata](https://github.com/sandermertens/flecs/blob/master/src/addons/meta/meta.c): `src/addons/meta/meta.c`
- [JSON serialization](https://github.com/sandermertens/flecs/blob/master/src/addons/json/json.c): `src/addons/json/json.c`
- [Script runtime](https://github.com/sandermertens/flecs/blob/master/src/addons/script/script.c): `src/addons/script/script.c`
- [Statistics monitoring](https://github.com/sandermertens/flecs/blob/master/src/addons/stats/stats.c): `src/addons/stats/stats.c`
- [REST interface](https://github.com/sandermertens/flecs/blob/master/src/addons/rest.c): `src/addons/rest.c`

### Language interfaces

- [C API](https://github.com/sandermertens/flecs/blob/master/include/flecs.h): `include/flecs.h`
- [C++ API](https://github.com/sandermertens/flecs/blob/master/include/flecs/addons/cpp/world.hpp): `include/flecs/addons/cpp/world.hpp`

### Other components

- **Application developer**

## Connections

- Application developer → C API: uses
- Application developer → C++ API: uses
- C API → ECS world: creates and configures
- C++ API → ECS world: wraps
- ECS world → Entities and IDs: manages
- Entities and IDs → Archetype storage: stores component sets
- Entities and IDs → Sparse components: stores sparse data
- Query API → Query compiler: compiles terms
- Query API → Query cache: maintains matches
- Query engine → Query cache: iterates matches
- Query engine → Archetype storage: matches tables
- Query engine → Sparse components: evaluates sparse data
- Systems → Query API: uses queries
- Pipeline scheduler → Systems: schedules systems
- Application loop → ECS world: progresses
- Application loop → Pipeline scheduler: runs via progress
- Systems → Archetype storage: processes component data
- Prefabs and hierarchy → Entities and IDs: instantiates entities
- Reflection and metadata → JSON serialization: provides type metadata
- JSON serialization → ECS world: serializes world data
- Script runtime → ECS world: evaluates against
- Application loop → REST interface: can enable
- Application loop → Statistics monitoring: can enable
- Statistics monitoring → Pipeline scheduler: monitors