# quantumleaps/qpc architecture

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

- Interactive diagram: https://gitdiagram.com/quantumleaps/qpc
- Repository: https://github.com/quantumleaps/qpc

## Overview

QP/C is a real-time event framework for embedded applications: applications model behavior with active objects and hierarchical state machines, while the runtime dispatches events under a selectable execution port. The graph preserves the documented state-machine and active-object capabilities plus distinct event, timing, and memory facilities visible in the source tree. Several implementation files are unsampled; links to those facilities are limited to README statements or SOURCE INDEX references rather than inferred call chains.

Main entry points: [`src/qf/qf_act.c`](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_act.c) (Active objects), [`ports/freertos/qf_port.c`](https://github.com/quantumleaps/qpc/blob/master/ports/freertos/qf_port.c) (FreeRTOS port), [`src/qf/qep_hsm.c`](https://github.com/quantumleaps/qpc/blob/master/src/qf/qep_hsm.c) (State machines), [`include/qsafe.h`](https://github.com/quantumleaps/qpc/blob/master/include/qsafe.h) (Safety checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["Event framework"]
  node_active_objects["Active objects<br/>[qf_act.c]"]
  node_event_queues["Event queues<br/>[qf_actq.c]"]
  node_publish_subscribe["Publish subscribe<br/>[qf_ps.c]"]
  node_deferred_events["Deferred events<br/>[qf_defer.c]"]
end

subgraph group_behavior["State behavior"]
  node_state_machines["State machines<br/>[qep_hsm.c]"]
  node_state_machine_core["State machine core<br/>[qep_msm.c]"]
end

subgraph group_execution["Execution and ports"]
  node_qk_kernel["QK kernel<br/>[qk.c]"]
  node_qv_kernel["QV kernel<br/>[qv.c]"]
  node_platform_ports["Platform ports"]
  node_zephyr_port["Zephyr port<br/>[qf_port.c]"]
  node_freertos_port["FreeRTOS port<br/>[qf_port.c]"]
  node_posix_qv_port["POSIX QV port<br/>[qf_port.c]"]
end

subgraph group_support["Runtime support"]
  node_time_events["Time events<br/>[qf_time.c]"]
  node_dynamic_events["Dynamic events<br/>[qf_dyn.c]"]
  node_memory_pools[("Memory pools<br/>[qf_mem.c]")]
  node_event_queue_api["Event queue API<br/>[qequeue.h]"]
  node_safety_checks["Safety checks<br/>[qsafe.h]"]
  node_timestamp["Timestamp utility<br/>[qstamp.c]"]
end

node_developer(("Application developer"))

node_developer -->|"defines behavior"| node_active_objects
node_active_objects -->|"uses statecharts"| node_state_machines
node_active_objects -.->|"queues events"| node_event_queues
node_active_objects -.->|"publishes events"| node_publish_subscribe
node_active_objects -.->|"defers events"| node_deferred_events
node_state_machines -.->|"shares interface"| node_state_machine_core
node_zephyr_port -->|"uses queue API"| node_event_queue_api
node_zephyr_port -->|"uses pools"| node_memory_pools
node_freertos_port -->|"posts events"| node_event_queues
node_freertos_port -->|"ticks timers"| node_time_events
node_freertos_port -->|"manages pools"| node_memory_pools
node_posix_qv_port -->|"signals clock ticks"| node_time_events
node_qk_kernel -.->|"has platform variants"| node_platform_ports
node_qv_kernel -.->|"has platform variants"| node_platform_ports
node_state_machines -->|"uses assertions"| node_safety_checks
node_qk_kernel -->|"uses assertions"| node_safety_checks
node_qv_kernel -->|"uses assertions"| node_safety_checks

click node_active_objects "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_act.c"
click node_event_queues "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_actq.c"
click node_publish_subscribe "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_ps.c"
click node_deferred_events "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_defer.c"
click node_state_machines "https://github.com/quantumleaps/qpc/blob/master/src/qf/qep_hsm.c"
click node_state_machine_core "https://github.com/quantumleaps/qpc/blob/master/src/qf/qep_msm.c"
click node_qk_kernel "https://github.com/quantumleaps/qpc/blob/master/src/qk/qk.c"
click node_qv_kernel "https://github.com/quantumleaps/qpc/blob/master/src/qv/qv.c"
click node_platform_ports "https://github.com/quantumleaps/qpc/tree/master/ports"
click node_zephyr_port "https://github.com/quantumleaps/qpc/blob/master/zephyr/qf_port.c"
click node_freertos_port "https://github.com/quantumleaps/qpc/blob/master/ports/freertos/qf_port.c"
click node_posix_qv_port "https://github.com/quantumleaps/qpc/blob/master/ports/posix-qv/qf_port.c"
click node_time_events "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_time.c"
click node_dynamic_events "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_dyn.c"
click node_memory_pools "https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_mem.c"
click node_event_queue_api "https://github.com/quantumleaps/qpc/blob/master/include/qequeue.h"
click node_safety_checks "https://github.com/quantumleaps/qpc/blob/master/include/qsafe.h"
click node_timestamp "https://github.com/quantumleaps/qpc/blob/master/src/qs/qstamp.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_active_objects,node_event_queues,node_publish_subscribe,node_deferred_events toneBlue
class node_state_machines,node_state_machine_core toneAmber
class node_qk_kernel,node_qv_kernel,node_platform_ports,node_zephyr_port,node_freertos_port,node_posix_qv_port toneMint
class node_time_events,node_dynamic_events,node_memory_pools,node_event_queue_api,node_safety_checks,node_timestamp toneRose
class node_developer toneIndigo
```

## Components

### Event framework

- [Active objects](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_act.c): `src/qf/qf_act.c`
- [Event queues](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_actq.c): `src/qf/qf_actq.c`
- [Publish subscribe](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_ps.c): `src/qf/qf_ps.c`
- [Deferred events](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_defer.c): `src/qf/qf_defer.c`

### State behavior

- [State machines](https://github.com/quantumleaps/qpc/blob/master/src/qf/qep_hsm.c): `src/qf/qep_hsm.c`
- [State machine core](https://github.com/quantumleaps/qpc/blob/master/src/qf/qep_msm.c): `src/qf/qep_msm.c`

### Execution and ports

- [QK kernel](https://github.com/quantumleaps/qpc/blob/master/src/qk/qk.c): `src/qk/qk.c`
- [QV kernel](https://github.com/quantumleaps/qpc/blob/master/src/qv/qv.c): `src/qv/qv.c`
- [Platform ports](https://github.com/quantumleaps/qpc/tree/master/ports): `ports`
- [Zephyr port](https://github.com/quantumleaps/qpc/blob/master/zephyr/qf_port.c): `zephyr/qf_port.c`
- [FreeRTOS port](https://github.com/quantumleaps/qpc/blob/master/ports/freertos/qf_port.c): `ports/freertos/qf_port.c`
- [POSIX QV port](https://github.com/quantumleaps/qpc/blob/master/ports/posix-qv/qf_port.c): `ports/posix-qv/qf_port.c`

### Runtime support

- [Time events](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_time.c): `src/qf/qf_time.c`
- [Dynamic events](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_dyn.c): `src/qf/qf_dyn.c`
- [Memory pools](https://github.com/quantumleaps/qpc/blob/master/src/qf/qf_mem.c): `src/qf/qf_mem.c`
- [Event queue API](https://github.com/quantumleaps/qpc/blob/master/include/qequeue.h): `include/qequeue.h`
- [Safety checks](https://github.com/quantumleaps/qpc/blob/master/include/qsafe.h): `include/qsafe.h`
- [Timestamp utility](https://github.com/quantumleaps/qpc/blob/master/src/qs/qstamp.c): `src/qs/qstamp.c`

### Other components

- **Application developer**

## Connections

- Application developer → Active objects: defines behavior (evidence: `README.md`)
- Active objects → State machines: uses statecharts (evidence: `README.md`)
- Active objects → Event queues: queues events
- Active objects → Publish subscribe: publishes events
- Active objects → Deferred events: defers events
- State machines → State machine core: shares interface
- Zephyr port → Event queue API: uses queue API
- Zephyr port → Memory pools: uses pools
- FreeRTOS port → Event queues: posts events (evidence: `ports/freertos/qf_port.c`)
- FreeRTOS port → Time events: ticks timers (evidence: `ports/freertos/qf_port.c`)
- FreeRTOS port → Memory pools: manages pools (evidence: `ports/freertos/qf_port.c`)
- POSIX QV port → Time events: signals clock ticks (evidence: `ports/posix-qv/qf_port.c`)
- QK kernel → Platform ports: has platform variants
- QV kernel → Platform ports: has platform variants
- State machines → Safety checks: uses assertions (evidence: `src/qf/qep_hsm.c`)
- QK kernel → Safety checks: uses assertions (evidence: `src/qk/qk.c`)
- QV kernel → Safety checks: uses assertions (evidence: `src/qv/qv.c`)