# amcolex/umsg architecture

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

- Interactive diagram: https://gitdiagram.com/amcolex/umsg
- Repository: https://github.com/amcolex/umsg

## Overview

μMsg is an embedded C publish-subscribe library with companion tools for generating typed topic APIs from JSON definitions and visualizing communication links in C source. The principal workflow is to define topics, generate a library, then have publisher and subscriber tasks use its typed API; the core dispatches published values to matching subscription queues. The graph tool separately scans application C files and emits a communication diagram. Relationships involving generated code and the graph tool’s output are documented or visible in the sampled implementation; unsampled application call sites are not asserted.

Main entry points: [`umsg_gen/umsg_gen/umsg_gen.py`](https://github.com/amcolex/umsg/blob/master/umsg_gen/umsg_gen/umsg_gen.py) (Topic generator), [`umsg_lib/core/src/umsg.c`](https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/umsg.c) (Dispatch core), [`umsg_lib/src/example.c`](https://github.com/amcolex/umsg/blob/master/umsg_lib/src/example.c) (Typed topic API), [`umsg_graph/umsg_graph/umsg_graph.py`](https://github.com/amcolex/umsg/blob/master/umsg_graph/umsg_graph/umsg_graph.py) (Graph analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definitions["Topic Definitions"]
  node_json_topics["JSON topics"]
end

subgraph group_generation["Code Generation"]
  node_generator["Topic generator<br/>[umsg_gen.py]"]
  node_templates["C templates"]
end

subgraph group_runtime["Pub-Sub Runtime"]
  node_generated_api["Typed topic API<br/>[example.c]"]
  node_core["Dispatch core<br/>[umsg.c]"]
  node_rtos_port["FreeRTOS port<br/>[port_freertos.c]"]
  node_posix_port["POSIX port<br/>[port_posix.c]"]
end

subgraph group_visualization["Communication Analysis"]
  node_graph_tool["Graph analyzer<br/>[umsg_graph.py]"]
end

node_author(("Library integrator"))
node_subscribers(("Subscriber tasks"))
node_application_sources["Application C sources"]
node_communication_graph["Communication graph"]

node_author -->|"defines topics"| node_json_topics
node_author -->|"runs generator"| node_generator
node_generator -->|"loads definitions"| node_json_topics
node_generator -->|"renders code"| node_templates
node_generator -->|"copies runtime"| node_core
node_generator -->|"generates API"| node_generated_api
node_author -->|"integrates library"| node_generated_api
node_subscribers -->|"subscribes and receives"| node_generated_api
node_generated_api -->|"delegates API calls"| node_core
node_core -->|"uses queue port"| node_rtos_port
node_core -.->|"uses queue port"| node_posix_port
node_author -->|"runs analyzer"| node_graph_tool
node_graph_tool -->|"scans C sources"| node_application_sources
node_graph_tool -->|"renders links"| node_communication_graph

click node_json_topics "https://github.com/amcolex/umsg/tree/master/msg_defs"
click node_generator "https://github.com/amcolex/umsg/blob/master/umsg_gen/umsg_gen/umsg_gen.py"
click node_templates "https://github.com/amcolex/umsg/tree/master/umsg_gen/umsg_gen/templates"
click node_generated_api "https://github.com/amcolex/umsg/blob/master/umsg_lib/src/example.c"
click node_core "https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/umsg.c"
click node_rtos_port "https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/port_freertos.c"
click node_posix_port "https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/port_posix.c"
click node_graph_tool "https://github.com/amcolex/umsg/blob/master/umsg_graph/umsg_graph/umsg_graph.py"

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_json_topics toneBlue
class node_generator,node_templates toneAmber
class node_generated_api,node_core,node_rtos_port,node_posix_port toneMint
class node_graph_tool,node_subscribers toneRose
class node_author,node_application_sources,node_communication_graph toneIndigo
```

## Components

### Topic Definitions

- [JSON topics](https://github.com/amcolex/umsg/tree/master/msg_defs): `msg_defs`

### Code Generation

- [Topic generator](https://github.com/amcolex/umsg/blob/master/umsg_gen/umsg_gen/umsg_gen.py): `umsg_gen/umsg_gen/umsg_gen.py`
- [C templates](https://github.com/amcolex/umsg/tree/master/umsg_gen/umsg_gen/templates): `umsg_gen/umsg_gen/templates`

### Pub-Sub Runtime

- [Typed topic API](https://github.com/amcolex/umsg/blob/master/umsg_lib/src/example.c): `umsg_lib/src/example.c`
- [Dispatch core](https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/umsg.c): `umsg_lib/core/src/umsg.c`
- [FreeRTOS port](https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/port_freertos.c): `umsg_lib/core/src/port_freertos.c`
- [POSIX port](https://github.com/amcolex/umsg/blob/master/umsg_lib/core/src/port_posix.c): `umsg_lib/core/src/port_posix.c`

### Communication Analysis

- [Graph analyzer](https://github.com/amcolex/umsg/blob/master/umsg_graph/umsg_graph/umsg_graph.py): `umsg_graph/umsg_graph/umsg_graph.py`

### Other components

- **Library integrator**
- **Subscriber tasks**
- **Application C sources**
- **Communication graph**

## Connections

- Library integrator → JSON topics: defines topics (evidence: `README.md`)
- Library integrator → Topic generator: runs generator (evidence: `README.md`)
- Topic generator → JSON topics: loads definitions (evidence: `umsg_gen/umsg_gen/umsg_gen.py`)
- Topic generator → C templates: renders code (evidence: `umsg_gen/umsg_gen/umsg_gen.py`)
- Topic generator → Dispatch core: copies runtime (evidence: `umsg_gen/umsg_gen/umsg_gen.py`)
- Topic generator → Typed topic API: generates API (evidence: `README.md`)
- Library integrator → Typed topic API: integrates library (evidence: `README.md`)
- Subscriber tasks → Typed topic API: subscribes and receives (evidence: `README.md`)
- Typed topic API → Dispatch core: delegates API calls (evidence: `umsg_lib/src/example.c`)
- Dispatch core → FreeRTOS port: uses queue port (evidence: `umsg_lib/core/src/umsg.c`)
- Dispatch core → POSIX port: uses queue port
- Library integrator → Graph analyzer: runs analyzer (evidence: `umsg_graph/umsg_graph/umsg_graph.py`)
- Graph analyzer → Application C sources: scans C sources (evidence: `umsg_graph/umsg_graph/umsg_graph.py`)
- Graph analyzer → Communication graph: renders links (evidence: `umsg_graph/umsg_graph/umsg_graph.py`)
