# durham-adaptive-optics/daobase architecture

> Architecture diagram of the GitHub repository durham-adaptive-optics/daobase, 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/durham-adaptive-optics/daobase
- Repository: https://github.com/durham-adaptive-optics/daobase

## Overview

daoBase is a real-time adaptive-optics control foundation, not the higher-level control application: it provides shared-memory image exchange, process coordination/messaging, and language bindings. A typical workflow creates or opens a shared image, writes frames and signals updates, and lets another process read them; the separate registry daemon can discover local segments and serve remote streams on demand. The README and tree establish the component/state-machine and messaging capabilities, but sampled excerpts do not expose all of their internal call paths, so uncertain wiring is omitted.

Main entry points: [`src/c/dao.c`](https://github.com/durham-adaptive-optics/daobase/blob/main/src/c/dao.c) (C SHM API), [`apps/daoServer.py`](https://github.com/durham-adaptive-optics/daobase/blob/main/apps/daoServer.py) (SHM registry daemon), [`src/python/daoShm.py`](https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoShm.py) (Python SHM), [`src/rust/src/lib.rs`](https://github.com/durham-adaptive-optics/daobase/blob/main/src/rust/src/lib.rs) (Rust SHM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shm["Shared memory"]
  node_capi["C SHM API<br/>[dao.c]"]
  node_shm_layout["IMAGE layout<br/>[dao.h]"]
  node_shm_store[("Shared image segments")]
  node_signals["Frame semaphores<br/>[dao.c]"]
end

subgraph group_bindings["Language interfaces"]
  node_python_shm["Python SHM<br/>[daoShm.py]"]
  node_rust_shm["Rust SHM<br/>[lib.rs]"]
  node_matlab_shm["MATLAB SHM<br/>[daomex.c]"]
  node_cpp_shm["C++ SHM interface<br/>[daoShmIfce.hpp]"]
end

subgraph group_runtime["Process runtime"]
  node_components["Components<br/>[daoComponent.hpp]"]
  node_state_machine["State machines"]
  node_threads["Component threads"]
  node_zmq_thread["ZMQ component thread"]
  node_commands["Command schema<br/>[daoCommand.proto]"]
  node_events["Event schema<br/>[daoEvent.proto]"]
  node_logging["Logging schema<br/>[daoLogging.proto]"]
  node_py_event["Python events<br/>[daoEvent.py]"]
  node_py_proxy["Python proxy<br/>[daoProxy.py]"]
  node_py_log["Python logging<br/>[daoLog.py]"]
end

subgraph group_distributed["Distributed access"]
  node_server["SHM registry daemon<br/>[daoServer.py]"]
  node_redis[("Redis registry")]
  node_file_protocol["File server schema"]
end

node_pipeline(("RTC processes"))
node_remote_client(("Remote clients"))

node_pipeline -->|"uses SHM"| node_python_shm
node_pipeline -->|"uses SHM"| node_rust_shm
node_pipeline -->|"uses SHM"| node_matlab_shm
node_pipeline -->|"uses SHM"| node_cpp_shm
node_python_shm -->|"calls"| node_capi
node_rust_shm -->|"calls FFI"| node_capi
node_matlab_shm -->|"calls"| node_capi
node_cpp_shm -->|"calls"| node_capi
node_capi -->|"uses layout"| node_shm_layout
node_capi -->|"creates / opens"| node_shm_store
node_capi -->|"waits / posts"| node_signals
node_python_shm -->|"reads / writes"| node_shm_store
node_rust_shm -->|"reads / writes"| node_shm_store
node_matlab_shm -->|"reads / writes"| node_shm_store
node_cpp_shm -->|"maps / accesses"| node_shm_store
node_components -->|"uses framework"| node_state_machine
node_components -->|"runs threads"| node_threads
node_zmq_thread -->|"uses schema"| node_commands
node_py_event -->|"uses schema"| node_events
node_py_log -->|"uses schema"| node_logging
node_py_proxy -.->|"communicates"| node_zmq_thread
node_server -->|"discovers segments"| node_shm_store
node_server -->|"registers / queries"| node_redis
node_remote_client -->|"requests stream"| node_server
node_server -->|"publishes frames"| node_remote_client
node_server -.->|"supports file API"| node_file_protocol

click node_capi "https://github.com/durham-adaptive-optics/daobase/blob/main/src/c/dao.c"
click node_shm_layout "https://github.com/durham-adaptive-optics/daobase/blob/main/include/dao.h"
click node_signals "https://github.com/durham-adaptive-optics/daobase/blob/main/src/c/dao.c"
click node_python_shm "https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoShm.py"
click node_rust_shm "https://github.com/durham-adaptive-optics/daobase/blob/main/src/rust/src/lib.rs"
click node_matlab_shm "https://github.com/durham-adaptive-optics/daobase/blob/main/src/matlab/daomex.c"
click node_cpp_shm "https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoShmIfce.hpp"
click node_components "https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoComponent.hpp"
click node_state_machine "https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoComponentStateMachine.py"
click node_threads "https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoComponentUpdateThread.hpp"
click node_zmq_thread "https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoComponentZmqThread.hpp"
click node_commands "https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoCommand.proto"
click node_events "https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoEvent.proto"
click node_logging "https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoLogging.proto"
click node_py_event "https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoEvent.py"
click node_py_proxy "https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoProxy.py"
click node_py_log "https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoLog.py"
click node_server "https://github.com/durham-adaptive-optics/daobase/blob/main/apps/daoServer.py"
click node_file_protocol "https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoFileServer.proto"

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_capi,node_shm_layout,node_shm_store,node_signals,node_remote_client toneBlue
class node_python_shm,node_rust_shm,node_matlab_shm,node_cpp_shm toneAmber
class node_components,node_state_machine,node_threads,node_zmq_thread,node_commands,node_events,node_logging,node_py_event,node_py_proxy,node_py_log toneMint
class node_server,node_redis,node_file_protocol toneRose
class node_pipeline toneIndigo
```

## Components

### Shared memory

- [C SHM API](https://github.com/durham-adaptive-optics/daobase/blob/main/src/c/dao.c): `src/c/dao.c`
- [IMAGE layout](https://github.com/durham-adaptive-optics/daobase/blob/main/include/dao.h): `include/dao.h`
- **Shared image segments**
- [Frame semaphores](https://github.com/durham-adaptive-optics/daobase/blob/main/src/c/dao.c): `src/c/dao.c`

### Language interfaces

- [Python SHM](https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoShm.py): `src/python/daoShm.py`
- [Rust SHM](https://github.com/durham-adaptive-optics/daobase/blob/main/src/rust/src/lib.rs): `src/rust/src/lib.rs`
- [MATLAB SHM](https://github.com/durham-adaptive-optics/daobase/blob/main/src/matlab/daomex.c): `src/matlab/daomex.c`
- [C++ SHM interface](https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoShmIfce.hpp): `include/daoShmIfce.hpp`

### Process runtime

- [Components](https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoComponent.hpp): `include/daoComponent.hpp`
- [State machines](https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoComponentStateMachine.py): `src/python/daoComponentStateMachine.py`
- [Component threads](https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoComponentUpdateThread.hpp): `include/daoComponentUpdateThread.hpp`
- [ZMQ component thread](https://github.com/durham-adaptive-optics/daobase/blob/main/include/daoComponentZmqThread.hpp): `include/daoComponentZmqThread.hpp`
- [Command schema](https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoCommand.proto): `proto/daoCommand.proto`
- [Event schema](https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoEvent.proto): `proto/daoEvent.proto`
- [Logging schema](https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoLogging.proto): `proto/daoLogging.proto`
- [Python events](https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoEvent.py): `src/python/daoEvent.py`
- [Python proxy](https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoProxy.py): `src/python/daoProxy.py`
- [Python logging](https://github.com/durham-adaptive-optics/daobase/blob/main/src/python/daoLog.py): `src/python/daoLog.py`

### Distributed access

- [SHM registry daemon](https://github.com/durham-adaptive-optics/daobase/blob/main/apps/daoServer.py): `apps/daoServer.py`
- **Redis registry**
- [File server schema](https://github.com/durham-adaptive-optics/daobase/blob/main/proto/daoFileServer.proto): `proto/daoFileServer.proto`

### Other components

- **RTC processes**
- **Remote clients**

## Connections

- RTC processes → Python SHM: uses SHM
- RTC processes → Rust SHM: uses SHM
- RTC processes → MATLAB SHM: uses SHM
- RTC processes → C++ SHM interface: uses SHM
- Python SHM → C SHM API: calls
- Rust SHM → C SHM API: calls FFI
- MATLAB SHM → C SHM API: calls
- C++ SHM interface → C SHM API: calls
- C SHM API → IMAGE layout: uses layout
- C SHM API → Shared image segments: creates / opens
- C SHM API → Frame semaphores: waits / posts
- Python SHM → Shared image segments: reads / writes
- Rust SHM → Shared image segments: reads / writes
- MATLAB SHM → Shared image segments: reads / writes
- C++ SHM interface → Shared image segments: maps / accesses
- Components → State machines: uses framework
- Components → Component threads: runs threads
- ZMQ component thread → Command schema: uses schema
- Python events → Event schema: uses schema
- Python logging → Logging schema: uses schema
- Python proxy → ZMQ component thread: communicates
- SHM registry daemon → Shared image segments: discovers segments
- SHM registry daemon → Redis registry: registers / queries
- Remote clients → SHM registry daemon: requests stream
- SHM registry daemon → Remote clients: publishes frames
- SHM registry daemon → File server schema: supports file API