# broadbandforum/obuspa architecture

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

- Interactive diagram: https://gitdiagram.com/broadbandforum/obuspa
- Repository: https://github.com/broadbandforum/obuspa

## Overview

OB-USP-Agent is a C reference implementation of the USP Agent: a Controller manages the Agent’s exposed Service Element data model, and the Agent processes USP messages and returns responses. The map highlights the data-model and persistence layer, request execution, message/record handling, and supported transport families, plus the public integration API. The README establishes the product workflow and SOURCE INDEX references establish module relationships; where those sources do not show a specific runtime call, the relationship is omitted or marked unverified.

Main entry points: [`src/core/msg_handler.c`](https://github.com/broadbandforum/obuspa/blob/master/src/core/msg_handler.c) (Message handling), [`src/core/main.c`](https://github.com/broadbandforum/obuspa/blob/master/src/core/main.c) (Agent startup), [`src/core/data_model.c`](https://github.com/broadbandforum/obuspa/blob/master/src/core/data_model.c) (Data model), [`src/core/mtp_exec.c`](https://github.com/broadbandforum/obuspa/blob/master/src/core/mtp_exec.c) (Transport execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_main["Agent startup<br/>[main.c]"]
  node_api["Agent API<br/>[usp_api.h]"]
  node_device_controller["Controller config"]
  node_device["Device interfaces<br/>[device.h]"]
  node_utilities["Core utilities<br/>[os_utils.h]"]
  node_text_utils["Text conversion<br/>[text_utils.h]"]
  node_iso8601["Date-time support<br/>[iso8601.c]"]
  node_dllist["List support<br/>[dllist.h]"]
  node_common_defs["Common definitions<br/>[common_defs.h]"]
end

subgraph group_model["Service data model"]
  node_data_model["Data model<br/>[data_model.c]"]
  node_database[("Parameter database<br/>[database.c]")]
  node_dm_exec["Request execution<br/>[dm_exec.c]"]
end

subgraph group_messaging["USP messaging"]
  node_msg_handler["Message handling<br/>[msg_handler.c]"]
  node_usp_record["USP records<br/>[usp_record.h]"]
  node_e2e["E2E sessions<br/>[e2e_context.c]"]
  node_usp_msg_proto["USP message schema<br/>[usp-msg.pb-c.h]"]
  node_usp_record_proto["USP record schema<br/>[usp-record.pb-c.h]"]
end

subgraph group_transports["Message transports"]
  node_mtp_exec["Transport execution<br/>[mtp_exec.c]"]
  node_coap["CoAP transport<br/>[coap_client.c]"]
  node_stomp["STOMP transport<br/>[stomp.c]"]
  node_mqtt["MQTT transport<br/>[mqtt.c]"]
  node_wsclient["WebSocket client<br/>[wsclient.c]"]
  node_wsserver["WebSocket server<br/>[wsserver.c]"]
  node_uds["Unix socket transport<br/>[uds.c]"]
end

node_controller(("USP Controller"))

node_controller -.->|"sends requests"| node_msg_handler
node_msg_handler -.->|"returns responses"| node_controller
node_main -.->|"starts execution"| node_dm_exec
node_main -.->|"initializes"| node_data_model
node_main -.->|"initializes"| node_database
node_msg_handler -.->|"dispatches requests"| node_dm_exec
node_msg_handler -.->|"uses records"| node_usp_record
node_msg_handler -.->|"uses sessions"| node_e2e
node_msg_handler -.->|"uses data model"| node_data_model
node_usp_record -.->|"uses transports"| node_mtp_exec
node_e2e -.->|"uses schema"| node_usp_record_proto
node_mtp_exec -.->|"uses messages"| node_usp_msg_proto
node_wsclient -.->|"uses message handler"| node_msg_handler
node_main -.->|"starts transport loop"| node_mtp_exec
node_device_controller -.->|"configures controllers"| node_data_model
node_api -.->|"exposes data model API"| node_data_model

click node_main "https://github.com/broadbandforum/obuspa/blob/master/src/core/main.c"
click node_api "https://github.com/broadbandforum/obuspa/blob/master/src/include/usp_api.h"
click node_device_controller "https://github.com/broadbandforum/obuspa/blob/master/src/core/device_controller.c"
click node_device "https://github.com/broadbandforum/obuspa/blob/master/src/core/device.h"
click node_data_model "https://github.com/broadbandforum/obuspa/blob/master/src/core/data_model.c"
click node_database "https://github.com/broadbandforum/obuspa/blob/master/src/core/database.c"
click node_dm_exec "https://github.com/broadbandforum/obuspa/blob/master/src/core/dm_exec.c"
click node_msg_handler "https://github.com/broadbandforum/obuspa/blob/master/src/core/msg_handler.c"
click node_usp_record "https://github.com/broadbandforum/obuspa/blob/master/src/core/usp_record.h"
click node_e2e "https://github.com/broadbandforum/obuspa/blob/master/src/core/e2e_context.c"
click node_usp_msg_proto "https://github.com/broadbandforum/obuspa/blob/master/src/protobuf-c/usp-msg.pb-c.h"
click node_usp_record_proto "https://github.com/broadbandforum/obuspa/blob/master/src/protobuf-c/usp-record.pb-c.h"
click node_mtp_exec "https://github.com/broadbandforum/obuspa/blob/master/src/core/mtp_exec.c"
click node_coap "https://github.com/broadbandforum/obuspa/blob/master/src/core/coap_client.c"
click node_stomp "https://github.com/broadbandforum/obuspa/blob/master/src/core/stomp.c"
click node_mqtt "https://github.com/broadbandforum/obuspa/blob/master/src/core/mqtt.c"
click node_wsclient "https://github.com/broadbandforum/obuspa/blob/master/src/core/wsclient.c"
click node_wsserver "https://github.com/broadbandforum/obuspa/blob/master/src/core/wsserver.c"
click node_uds "https://github.com/broadbandforum/obuspa/blob/master/src/core/uds.c"
click node_utilities "https://github.com/broadbandforum/obuspa/blob/master/src/core/os_utils.h"
click node_text_utils "https://github.com/broadbandforum/obuspa/blob/master/src/core/text_utils.h"
click node_iso8601 "https://github.com/broadbandforum/obuspa/blob/master/src/core/iso8601.c"
click node_dllist "https://github.com/broadbandforum/obuspa/blob/master/src/core/dllist.h"
click node_common_defs "https://github.com/broadbandforum/obuspa/blob/master/src/core/common_defs.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_main,node_api,node_device_controller,node_device,node_utilities,node_text_utils,node_iso8601,node_dllist,node_common_defs toneBlue
class node_data_model,node_database,node_dm_exec toneAmber
class node_msg_handler,node_usp_record,node_e2e,node_usp_msg_proto,node_usp_record_proto toneMint
class node_mtp_exec,node_coap,node_stomp,node_mqtt,node_wsclient,node_wsserver,node_uds toneRose
class node_controller toneIndigo
```

## Components

### Agent runtime

- [Agent startup](https://github.com/broadbandforum/obuspa/blob/master/src/core/main.c): `src/core/main.c`
- [Agent API](https://github.com/broadbandforum/obuspa/blob/master/src/include/usp_api.h): `src/include/usp_api.h`
- [Controller config](https://github.com/broadbandforum/obuspa/blob/master/src/core/device_controller.c): `src/core/device_controller.c`
- [Device interfaces](https://github.com/broadbandforum/obuspa/blob/master/src/core/device.h): `src/core/device.h`
- [Core utilities](https://github.com/broadbandforum/obuspa/blob/master/src/core/os_utils.h): `src/core/os_utils.h`
- [Text conversion](https://github.com/broadbandforum/obuspa/blob/master/src/core/text_utils.h): `src/core/text_utils.h`
- [Date-time support](https://github.com/broadbandforum/obuspa/blob/master/src/core/iso8601.c): `src/core/iso8601.c`
- [List support](https://github.com/broadbandforum/obuspa/blob/master/src/core/dllist.h): `src/core/dllist.h`
- [Common definitions](https://github.com/broadbandforum/obuspa/blob/master/src/core/common_defs.h): `src/core/common_defs.h`

### Service data model

- [Data model](https://github.com/broadbandforum/obuspa/blob/master/src/core/data_model.c): `src/core/data_model.c`
- [Parameter database](https://github.com/broadbandforum/obuspa/blob/master/src/core/database.c): `src/core/database.c`
- [Request execution](https://github.com/broadbandforum/obuspa/blob/master/src/core/dm_exec.c): `src/core/dm_exec.c`

### USP messaging

- [Message handling](https://github.com/broadbandforum/obuspa/blob/master/src/core/msg_handler.c): `src/core/msg_handler.c`
- [USP records](https://github.com/broadbandforum/obuspa/blob/master/src/core/usp_record.h): `src/core/usp_record.h`
- [E2E sessions](https://github.com/broadbandforum/obuspa/blob/master/src/core/e2e_context.c): `src/core/e2e_context.c`
- [USP message schema](https://github.com/broadbandforum/obuspa/blob/master/src/protobuf-c/usp-msg.pb-c.h): `src/protobuf-c/usp-msg.pb-c.h`
- [USP record schema](https://github.com/broadbandforum/obuspa/blob/master/src/protobuf-c/usp-record.pb-c.h): `src/protobuf-c/usp-record.pb-c.h`

### Message transports

- [Transport execution](https://github.com/broadbandforum/obuspa/blob/master/src/core/mtp_exec.c): `src/core/mtp_exec.c`
- [CoAP transport](https://github.com/broadbandforum/obuspa/blob/master/src/core/coap_client.c): `src/core/coap_client.c`
- [STOMP transport](https://github.com/broadbandforum/obuspa/blob/master/src/core/stomp.c): `src/core/stomp.c`
- [MQTT transport](https://github.com/broadbandforum/obuspa/blob/master/src/core/mqtt.c): `src/core/mqtt.c`
- [WebSocket client](https://github.com/broadbandforum/obuspa/blob/master/src/core/wsclient.c): `src/core/wsclient.c`
- [WebSocket server](https://github.com/broadbandforum/obuspa/blob/master/src/core/wsserver.c): `src/core/wsserver.c`
- [Unix socket transport](https://github.com/broadbandforum/obuspa/blob/master/src/core/uds.c): `src/core/uds.c`

### Other components

- **USP Controller**

## Connections

- USP Controller → Message handling: sends requests
- Message handling → USP Controller: returns responses
- Agent startup → Request execution: starts execution (evidence: `src/core/main.c`)
- Agent startup → Data model: initializes (evidence: `src/core/main.c`)
- Agent startup → Parameter database: initializes (evidence: `src/core/main.c`)
- Message handling → Request execution: dispatches requests (evidence: `src/core/msg_handler.c`)
- Message handling → USP records: uses records (evidence: `src/core/msg_handler.c`)
- Message handling → E2E sessions: uses sessions (evidence: `src/core/msg_handler.c`)
- Message handling → Data model: uses data model (evidence: `src/core/msg_handler.c`)
- USP records → Transport execution: uses transports (evidence: `src/core/usp_record.h`)
- E2E sessions → USP record schema: uses schema
- Transport execution → USP message schema: uses messages
- WebSocket client → Message handling: uses message handler (evidence: `src/core/wsclient.c`)
- Agent startup → Transport execution: starts transport loop (evidence: `src/core/main.c`)
- Controller config → Data model: configures controllers (evidence: `src/core/device_controller.c`)
- Agent API → Data model: exposes data model API (evidence: `src/include/usp_api.h`)
