# carbonengine/fsd architecture

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

- Interactive diagram: https://gitdiagram.com/carbonengine/fsd
- Repository: https://github.com/carbonengine/fsd

## Overview

FSD is a C++ binary-data reader exposed as a Python extension. A Python caller imports the package, which loads the native extension through Blue; the extension registers Python-facing types, and the binary loader decodes values according to schema metadata into primitives, vectors, objects, lists, or dictionaries. Objects and lists load nested values on access, while dictionaries use footer-based offset lookup. The README gives only a high-level product description; detailed format stages and some subsystem wiring are limited to the sampled source.

Main entry points: [`BinaryLoader.cpp`](https://github.com/carbonengine/fsd/blob/main/BinaryLoader.cpp) (Binary loader), [`FsdDict.cpp`](https://github.com/carbonengine/fsd/blob/main/FsdDict.cpp) (Dictionary access), [`python/pyFSD/__init__.py`](https://github.com/carbonengine/fsd/blob/main/python/pyFSD/__init__.py) (FSD package), [`pyFSD.cpp`](https://github.com/carbonengine/fsd/blob/main/pyFSD.cpp) (Extension registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_api["Python API"]
  node_package["FSD package<br/>[__init__.py]"]
  node_blue{{"Blue loader"}}
  node_extension["Extension registration<br/>[pyFSD.cpp]"]
end

subgraph group_decode["Binary Decoding"]
  node_binary["Binary loader<br/>[BinaryLoader.cpp]"]
end

subgraph group_containers["FSD Containers"]
  node_object["Object access<br/>[FsdObject.cpp]"]
  node_list["List access<br/>[FsdList.cpp]"]
  node_dict["Dictionary access<br/>[FsdDict.cpp]"]
  node_vector["Vector access<br/>[FsdVector.cpp]"]
  node_keymap["Integer key map"]
end

subgraph group_schema_index["Schema and Index"]
  node_schema["Schema metadata<br/>[FsdSchema.cpp]"]
  node_offsets["Footer offset lookup"]
end

node_caller(("Python caller"))

node_caller -->|"imports"| node_package
node_package -->|"loads extension"| node_blue
node_blue -->|"loads module"| node_extension
node_extension -->|"registers bindings"| node_binary
node_binary -->|"uses metadata"| node_schema
node_binary -->|"creates objects"| node_object
node_binary -->|"creates lists"| node_list
node_binary -->|"creates dictionaries"| node_dict
node_binary -->|"creates vectors"| node_vector
node_object -->|"loads attributes"| node_binary
node_list -->|"loads elements"| node_binary
node_dict -->|"looks up keys"| node_offsets
node_dict -->|"loads values"| node_binary

click node_package "https://github.com/carbonengine/fsd/blob/main/python/pyFSD/__init__.py"
click node_extension "https://github.com/carbonengine/fsd/blob/main/pyFSD.cpp"
click node_binary "https://github.com/carbonengine/fsd/blob/main/BinaryLoader.cpp"
click node_schema "https://github.com/carbonengine/fsd/blob/main/FsdSchema.cpp"
click node_object "https://github.com/carbonengine/fsd/blob/main/FsdObject.cpp"
click node_list "https://github.com/carbonengine/fsd/blob/main/FsdList.cpp"
click node_dict "https://github.com/carbonengine/fsd/blob/main/FsdDict.cpp"
click node_offsets "https://github.com/carbonengine/fsd/blob/main/FsdDictOffsetLookup.cpp"
click node_vector "https://github.com/carbonengine/fsd/blob/main/FsdVector.cpp"
click node_keymap "https://github.com/carbonengine/fsd/blob/main/FsdUnsignedIntegerKeyMap.cpp"

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_package,node_blue,node_extension toneBlue
class node_binary toneAmber
class node_object,node_list,node_dict,node_vector,node_keymap toneMint
class node_schema,node_offsets toneRose
class node_caller toneIndigo
```

## Components

### Python API

- [FSD package](https://github.com/carbonengine/fsd/blob/main/python/pyFSD/__init__.py): `python/pyFSD/__init__.py`
- **Blue loader**
- [Extension registration](https://github.com/carbonengine/fsd/blob/main/pyFSD.cpp): `pyFSD.cpp`

### Binary Decoding

- [Binary loader](https://github.com/carbonengine/fsd/blob/main/BinaryLoader.cpp): `BinaryLoader.cpp`

### FSD Containers

- [Object access](https://github.com/carbonengine/fsd/blob/main/FsdObject.cpp): `FsdObject.cpp`
- [List access](https://github.com/carbonengine/fsd/blob/main/FsdList.cpp): `FsdList.cpp`
- [Dictionary access](https://github.com/carbonengine/fsd/blob/main/FsdDict.cpp): `FsdDict.cpp`
- [Vector access](https://github.com/carbonengine/fsd/blob/main/FsdVector.cpp): `FsdVector.cpp`
- [Integer key map](https://github.com/carbonengine/fsd/blob/main/FsdUnsignedIntegerKeyMap.cpp): `FsdUnsignedIntegerKeyMap.cpp`

### Schema and Index

- [Schema metadata](https://github.com/carbonengine/fsd/blob/main/FsdSchema.cpp): `FsdSchema.cpp`
- [Footer offset lookup](https://github.com/carbonengine/fsd/blob/main/FsdDictOffsetLookup.cpp): `FsdDictOffsetLookup.cpp`

### Other components

- **Python caller**

## Connections

- Python caller → FSD package: imports
- FSD package → Blue loader: loads extension
- Blue loader → Extension registration: loads module
- Extension registration → Binary loader: registers bindings
- Binary loader → Schema metadata: uses metadata
- Binary loader → Object access: creates objects
- Binary loader → List access: creates lists
- Binary loader → Dictionary access: creates dictionaries
- Binary loader → Vector access: creates vectors
- Object access → Binary loader: loads attributes
- List access → Binary loader: loads elements
- Dictionary access → Footer offset lookup: looks up keys
- Dictionary access → Binary loader: loads values