# carbonengine/blue architecture

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

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

## Overview

carbon-blue is a central native library for an embedded Python runtime, game-loop services, resource loading, networking, and supporting platform facilities. The principal workflow is an application entering through Blue’s Python-facing runtime, which exposes services used by Python code; resource and data-format facilities provide additional capabilities. The tree and excerpts identify these subsystems, but sampled implementation evidence is limited, so uncertain internal wiring is intentionally omitted.

Main entry points: [`src/BluePython.cpp`](https://github.com/carbonengine/blue/blob/main/src/BluePython.cpp) (Python runtime), [`python/bluepycore/_taskletextension.py`](https://github.com/carbonengine/blue/blob/main/python/bluepycore/_taskletextension.py) (Tasklet extensions), [`include/stacklessio.h`](https://github.com/carbonengine/blue/blob/main/include/stacklessio.h) (Async I/O queue), [`src/BlueNet.cpp`](https://github.com/carbonengine/blue/blob/main/src/BlueNet.cpp) (BlueNet messaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and scheduling"]
  node_python["Python runtime<br/>[BluePython.cpp]"]
  node_tasklets["Tasklet extensions"]
  node_shutdown["Python shutdown<br/>[_shutdown.py]"]
  node_asyncio["Async I/O queue<br/>[stacklessio.h]"]
  node_tasktimer["Tasklet timer<br/>[TaskletTimer.cpp]"]
end

subgraph group_resources["Resource loading"]
  node_resman["Resource manager<br/>[BlueResMan.cpp]"]
  node_asyncres["Async resources<br/>[BlueAsyncRes.cpp]"]
  node_localfs["Local resource FS"]
  node_remotefs["Remote resource FS"]
  node_remotecache["Remote file cache"]
  node_streams["Resource streams"]
end

subgraph group_data["Networking and data"]
  node_formats["Data readers writers<br/>[BlackReader.cpp]"]
  node_yaml["YAML formats<br/>[YamlReader.cpp]"]
  node_bluenet["BlueNet messaging<br/>[BlueNet.cpp]"]
  node_networkstream["Network streams"]
end

subgraph group_services["Platform services"]
  node_logging["Logging<br/>[Logger.cpp]"]
  node_statistics["Statistics<br/>[BlueStatistics.cpp]"]
  node_os["OS services<br/>[BlueOS.cpp]"]
  node_paths["Path services<br/>[BluePaths.cpp]"]
end

node_application(("Host application"))

node_application -->|"enters runtime"| node_python
node_tasklets -->|"tracks tasklets"| node_tasktimer
node_asyncio -->|"dispatches events"| node_application
node_python -->|"shuts down"| node_shutdown
node_bluenet -->|"uses transport"| node_networkstream

click node_python "https://github.com/carbonengine/blue/blob/main/src/BluePython.cpp"
click node_tasklets "https://github.com/carbonengine/blue/blob/main/python/bluepycore/_taskletextension.py"
click node_shutdown "https://github.com/carbonengine/blue/blob/main/python/bluepycore/_shutdown.py"
click node_asyncio "https://github.com/carbonengine/blue/blob/main/include/stacklessio.h"
click node_tasktimer "https://github.com/carbonengine/blue/blob/main/src/TaskletTimer.cpp"
click node_resman "https://github.com/carbonengine/blue/blob/main/src/BlueResMan.cpp"
click node_asyncres "https://github.com/carbonengine/blue/blob/main/src/BlueAsyncRes.cpp"
click node_localfs "https://github.com/carbonengine/blue/blob/main/src/BlueResFileSystemLocal.cpp"
click node_remotefs "https://github.com/carbonengine/blue/blob/main/src/BlueResFileSystemRemote.cpp"
click node_remotecache "https://github.com/carbonengine/blue/blob/main/src/RemoteFileCache.cpp"
click node_streams "https://github.com/carbonengine/blue/blob/main/src/BlueRemoteStream.cpp"
click node_formats "https://github.com/carbonengine/blue/blob/main/src/BlackReader.cpp"
click node_yaml "https://github.com/carbonengine/blue/blob/main/src/YamlReader.cpp"
click node_bluenet "https://github.com/carbonengine/blue/blob/main/src/BlueNet.cpp"
click node_networkstream "https://github.com/carbonengine/blue/blob/main/src/BlueNetworkStream.cpp"
click node_logging "https://github.com/carbonengine/blue/blob/main/src/Logger/Logger.cpp"
click node_statistics "https://github.com/carbonengine/blue/blob/main/src/BlueStatistics.cpp"
click node_os "https://github.com/carbonengine/blue/blob/main/src/BlueOS.cpp"
click node_paths "https://github.com/carbonengine/blue/blob/main/src/BluePaths.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_python,node_tasklets,node_shutdown,node_asyncio,node_tasktimer toneBlue
class node_resman,node_asyncres,node_localfs,node_remotefs,node_remotecache,node_streams toneAmber
class node_formats,node_yaml,node_bluenet,node_networkstream toneMint
class node_logging,node_statistics,node_os,node_paths toneRose
class node_application toneIndigo
```

## Components

### Runtime and scheduling

- [Python runtime](https://github.com/carbonengine/blue/blob/main/src/BluePython.cpp): `src/BluePython.cpp`
- [Tasklet extensions](https://github.com/carbonengine/blue/blob/main/python/bluepycore/_taskletextension.py): `python/bluepycore/_taskletextension.py`
- [Python shutdown](https://github.com/carbonengine/blue/blob/main/python/bluepycore/_shutdown.py): `python/bluepycore/_shutdown.py`
- [Async I/O queue](https://github.com/carbonengine/blue/blob/main/include/stacklessio.h): `include/stacklessio.h`
- [Tasklet timer](https://github.com/carbonengine/blue/blob/main/src/TaskletTimer.cpp): `src/TaskletTimer.cpp`

### Resource loading

- [Resource manager](https://github.com/carbonengine/blue/blob/main/src/BlueResMan.cpp): `src/BlueResMan.cpp`
- [Async resources](https://github.com/carbonengine/blue/blob/main/src/BlueAsyncRes.cpp): `src/BlueAsyncRes.cpp`
- [Local resource FS](https://github.com/carbonengine/blue/blob/main/src/BlueResFileSystemLocal.cpp): `src/BlueResFileSystemLocal.cpp`
- [Remote resource FS](https://github.com/carbonengine/blue/blob/main/src/BlueResFileSystemRemote.cpp): `src/BlueResFileSystemRemote.cpp`
- [Remote file cache](https://github.com/carbonengine/blue/blob/main/src/RemoteFileCache.cpp): `src/RemoteFileCache.cpp`
- [Resource streams](https://github.com/carbonengine/blue/blob/main/src/BlueRemoteStream.cpp): `src/BlueRemoteStream.cpp`

### Networking and data

- [Data readers writers](https://github.com/carbonengine/blue/blob/main/src/BlackReader.cpp): `src/BlackReader.cpp`
- [YAML formats](https://github.com/carbonengine/blue/blob/main/src/YamlReader.cpp): `src/YamlReader.cpp`
- [BlueNet messaging](https://github.com/carbonengine/blue/blob/main/src/BlueNet.cpp): `src/BlueNet.cpp`
- [Network streams](https://github.com/carbonengine/blue/blob/main/src/BlueNetworkStream.cpp): `src/BlueNetworkStream.cpp`

### Platform services

- [Logging](https://github.com/carbonengine/blue/blob/main/src/Logger/Logger.cpp): `src/Logger/Logger.cpp`
- [Statistics](https://github.com/carbonengine/blue/blob/main/src/BlueStatistics.cpp): `src/BlueStatistics.cpp`
- [OS services](https://github.com/carbonengine/blue/blob/main/src/BlueOS.cpp): `src/BlueOS.cpp`
- [Path services](https://github.com/carbonengine/blue/blob/main/src/BluePaths.cpp): `src/BluePaths.cpp`

### Other components

- **Host application**

## Connections

- Host application → Python runtime: enters runtime
- Tasklet extensions → Tasklet timer: tracks tasklets
- Async I/O queue → Host application: dispatches events
- Python runtime → Python shutdown: shuts down
- BlueNet messaging → Network streams: uses transport