# david-feldt/botos architecture

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

- Interactive diagram: https://gitdiagram.com/david-feldt/botos
- Repository: https://github.com/david-feldt/botos

## Overview

botOS is a modular robotics runtime: a user defines components and typed channels, then runs them through the CLI. Runtime loads project configuration, starts a TCP router, and launches selected Python or C/C++ components; component clients register channels and exchange sensor or command messages through the router. The README also documents project scaffolding and group-based execution. Source excerpts establish Python client, C header, framing, routing, and orchestration; install and shell-integration details are not mapped.

Main entry points: [`src/router.py`](https://github.com/david-feldt/botos/blob/main/src/router.py) (TCP router), [`src/runtime.py`](https://github.com/david-feldt/botos/blob/main/src/runtime.py) (Runtime), [`src/cli.py`](https://github.com/david-feldt/botos/blob/main/src/cli.py) (bot CLI), [`src/bot.py`](https://github.com/david-feldt/botos/blob/main/src/bot.py) (Python client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Project setup"]
  node_cli["bot CLI<br/>[cli.py]"]
  node_project_config["Project config"]
end

subgraph group_runtime["Runtime orchestration"]
  node_runtime["Runtime<br/>[runtime.py]"]
  node_config_loader["Config loader<br/>[config.py]"]
end

subgraph group_messaging["Channel messaging"]
  node_router["TCP router<br/>[router.py]"]
  node_protocol["JSON framing<br/>[protocol.py]"]
end

subgraph group_clients["Component clients"]
  node_python_client["Python client<br/>[bot.py]"]
  node_c_client["C client<br/>[botos.h]"]
end

node_engineer(("Robot developer"))
node_components["Robot components"]

node_engineer -->|"runs commands"| node_cli
node_cli -->|"scaffolds project"| node_project_config
node_cli -->|"starts run"| node_runtime
node_runtime -->|"loads config"| node_config_loader
node_config_loader -->|"reads"| node_project_config
node_runtime -->|"starts process"| node_router
node_runtime -->|"launches selected"| node_components
node_components -->|"uses Python API"| node_python_client
node_components -->|"uses C API"| node_c_client
node_python_client -->|"registers and writes"| node_router
node_c_client -->|"registers and writes"| node_router
node_router -->|"delivers messages"| node_python_client
node_router -->|"delivers messages"| node_c_client
node_router -->|"frames TCP messages"| node_protocol

click node_cli "https://github.com/david-feldt/botos/blob/main/src/cli.py"
click node_runtime "https://github.com/david-feldt/botos/blob/main/src/runtime.py"
click node_config_loader "https://github.com/david-feldt/botos/blob/main/src/config.py"
click node_router "https://github.com/david-feldt/botos/blob/main/src/router.py"
click node_protocol "https://github.com/david-feldt/botos/blob/main/src/protocol.py"
click node_python_client "https://github.com/david-feldt/botos/blob/main/src/bot.py"
click node_c_client "https://github.com/david-feldt/botos/blob/main/src/botos_c/botos.h"

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_cli,node_project_config toneBlue
class node_runtime,node_config_loader toneAmber
class node_router,node_protocol toneMint
class node_python_client,node_c_client toneRose
class node_engineer,node_components toneIndigo
```

## Components

### Project setup

- [bot CLI](https://github.com/david-feldt/botos/blob/main/src/cli.py): `src/cli.py`
- **Project config**

### Runtime orchestration

- [Runtime](https://github.com/david-feldt/botos/blob/main/src/runtime.py): `src/runtime.py`
- [Config loader](https://github.com/david-feldt/botos/blob/main/src/config.py): `src/config.py`

### Channel messaging

- [TCP router](https://github.com/david-feldt/botos/blob/main/src/router.py): `src/router.py`
- [JSON framing](https://github.com/david-feldt/botos/blob/main/src/protocol.py): `src/protocol.py`

### Component clients

- [Python client](https://github.com/david-feldt/botos/blob/main/src/bot.py): `src/bot.py`
- [C client](https://github.com/david-feldt/botos/blob/main/src/botos_c/botos.h): `src/botos_c/botos.h`

### Other components

- **Robot developer**
- **Robot components**

## Connections

- Robot developer → bot CLI: runs commands
- bot CLI → Project config: scaffolds project
- bot CLI → Runtime: starts run
- Runtime → Config loader: loads config
- Config loader → Project config: reads
- Runtime → TCP router: starts process
- Runtime → Robot components: launches selected
- Robot components → Python client: uses Python API
- Robot components → C client: uses C API
- Python client → TCP router: registers and writes
- C client → TCP router: registers and writes
- TCP router → Python client: delivers messages
- TCP router → C client: delivers messages
- TCP router → JSON framing: frames TCP messages