# cosmo-wander-ai/cosmo-edge architecture

> Architecture diagram of the GitHub repository cosmo-wander-ai/cosmo-edge, 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/cosmo-wander-ai/cosmo-edge
- Repository: https://github.com/cosmo-wander-ai/cosmo-edge

## Overview

CosmoEdge is a C++ edge-video AI engine and application layer for deploying detection, VLM, and event workflows across Sophon, Rockchip, and x86. The principal workflow is configuring a task, running video through a platform-specific inference path, and exposing detections and alarms through application interfaces. The graph also retains model management, face-library queries, MQTT, storage cleanup, and observability as documented or tree-visible capabilities. Several runtime links are dashed because their connecting implementation was not sampled.

Main entry points: [`src/api/ApiRouterRoutes.cc`](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/api/ApiRouterRoutes.cc) (API Routes), [`src/api/MessageFaceLibHandler_Query.cc`](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/api/MessageFaceLibHandler_Query.cc) (Face Queries), [`src/service/task/impl/TaskServiceQuery.cc`](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/task/impl/TaskServiceQuery.cc) (Task Service), [`src/nn/pipeline/detection_pipeline.cc`](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/pipeline/detection_pipeline.cc) (Detection Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_web["Web Console<br/>[main.js]"]
  node_api["API Routes<br/>[ApiRouterRoutes.cc]"]
  node_facehandler["Face Queries"]
end

subgraph group_workflow["Video Workflows"]
  node_taskservice["Task Service"]
  node_taskflow["Task &amp; Channel"]
  node_logic["Logic Evaluation<br/>[LogicCalcEngine.cc]"]
  node_media["Video Ingest"]
end

subgraph group_inference["AI Inference"]
  node_detection["Detection Pipeline"]
  node_advanced["Advanced Pipelines"]
  node_backend["Inference Backends<br/>[RkllmVlmBackend.cc]"]
end

subgraph group_services["Services &amp; Events"]
  node_modelservice["Model Management"]
  node_face["Face Library<br/>[FaceManager.cc]"]
  node_alarm["Alarm Records"]
  node_mqtt["MQTT Client<br/>[MqttClient.cc]"]
  node_persondao[("Person Persistence<br/>[PersonDaoQuery.cc]")]
end

subgraph group_ops["Operations"]
  node_metrics["Inference Metrics"]
  node_previewmetrics["Preview Metrics"]
  node_storage["Storage Cleanup<br/>[StorageSpace.cc]"]
end

node_operator(("Operator"))

node_operator -.->|"configures"| node_web
node_web -.->|"sends requests"| node_api
node_api -.->|"dispatches tasks"| node_taskservice
node_taskservice -->|"reads channels"| node_taskflow
node_taskservice -.->|"queries alarms"| node_alarm
node_taskflow -.->|"processes video"| node_media
node_taskflow -.->|"runs inference"| node_detection
node_taskflow -.->|"runs VLM"| node_advanced
node_detection -.->|"uses backend"| node_backend
node_advanced -.->|"uses backend"| node_backend
node_taskflow -.->|"evaluates rules"| node_logic
node_logic -.->|"raises alarms"| node_alarm
node_api -.->|"routes queries"| node_facehandler
node_facehandler -->|"queries libraries"| node_face
node_facehandler -->|"queries people"| node_persondao
node_taskflow -.->|"delivers events"| node_mqtt
node_detection -.->|"records metrics"| node_metrics
node_media -.->|"records preview stats"| node_previewmetrics
node_storage -->|"queries records"| node_alarm

click node_web "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/web/src/main.js"
click node_api "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/api/ApiRouterRoutes.cc"
click node_facehandler "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/api/MessageFaceLibHandler_Query.cc"
click node_taskservice "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/task/impl/TaskServiceQuery.cc"
click node_logic "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/flow/logical/LogicCalcEngine.cc"
click node_modelservice "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/model/impl/ModelServiceImpl_Query.cc"
click node_face "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/flow/face/FaceManager.cc"
click node_mqtt "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/network/mqtt/MqttClient.cc"
click node_detection "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/pipeline/detection_pipeline.cc"
click node_advanced "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/pipeline/advanced_pipeline.cc"
click node_backend "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/infer/RkllmVlmBackend.cc"
click node_metrics "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/core/inference_pipeline_metrics.cc"
click node_previewmetrics "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/media/PreviewPipelineMetrics.cc"
click node_storage "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/infra/impl/StorageSpace.cc"
click node_persondao "https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/db/PersonDaoQuery.cc"

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_web,node_api,node_facehandler toneBlue
class node_taskservice,node_taskflow,node_logic,node_media toneAmber
class node_detection,node_advanced,node_backend toneMint
class node_modelservice,node_face,node_alarm,node_mqtt,node_persondao toneRose
class node_metrics,node_previewmetrics,node_storage,node_operator toneIndigo
```

## Components

### Application

- [Web Console](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/web/src/main.js): `src/web/src/main.js`
- [API Routes](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/api/ApiRouterRoutes.cc): `src/api/ApiRouterRoutes.cc`
- [Face Queries](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/api/MessageFaceLibHandler_Query.cc): `src/api/MessageFaceLibHandler_Query.cc`

### Video Workflows

- [Task Service](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/task/impl/TaskServiceQuery.cc): `src/service/task/impl/TaskServiceQuery.cc`
- **Task & Channel**
- [Logic Evaluation](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/flow/logical/LogicCalcEngine.cc): `src/flow/logical/LogicCalcEngine.cc`
- **Video Ingest**

### AI Inference

- [Detection Pipeline](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/pipeline/detection_pipeline.cc): `src/nn/pipeline/detection_pipeline.cc`
- [Advanced Pipelines](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/pipeline/advanced_pipeline.cc): `src/nn/pipeline/advanced_pipeline.cc`
- [Inference Backends](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/infer/RkllmVlmBackend.cc): `src/infer/RkllmVlmBackend.cc`

### Services & Events

- [Model Management](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/model/impl/ModelServiceImpl_Query.cc): `src/service/model/impl/ModelServiceImpl_Query.cc`
- [Face Library](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/flow/face/FaceManager.cc): `src/flow/face/FaceManager.cc`
- **Alarm Records**
- [MQTT Client](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/network/mqtt/MqttClient.cc): `src/network/mqtt/MqttClient.cc`
- [Person Persistence](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/db/PersonDaoQuery.cc): `src/db/PersonDaoQuery.cc`

### Operations

- [Inference Metrics](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/nn/core/inference_pipeline_metrics.cc): `src/nn/core/inference_pipeline_metrics.cc`
- [Preview Metrics](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/media/PreviewPipelineMetrics.cc): `src/media/PreviewPipelineMetrics.cc`
- [Storage Cleanup](https://github.com/cosmo-wander-ai/cosmo-edge/blob/main/src/service/infra/impl/StorageSpace.cc): `src/service/infra/impl/StorageSpace.cc`

### Other components

- **Operator**

## Connections

- Operator → Web Console: configures · Inferred; not shown in the code that was read.
- Web Console → API Routes: sends requests · Inferred; not shown in the code that was read.
- API Routes → Task Service: dispatches tasks · Inferred; not shown in the code that was read.
- Task Service → Task & Channel: reads channels (evidence: `src/service/task/impl/TaskServiceQuery.cc`)
- Task Service → Alarm Records: queries alarms · Inferred; not shown in the code that was read.
- Task & Channel → Video Ingest: processes video · Inferred; not shown in the code that was read.
- Task & Channel → Detection Pipeline: runs inference · Inferred; not shown in the code that was read.
- Task & Channel → Advanced Pipelines: runs VLM · Inferred; not shown in the code that was read.
- Detection Pipeline → Inference Backends: uses backend · Inferred; not shown in the code that was read.
- Advanced Pipelines → Inference Backends: uses backend · Inferred; not shown in the code that was read.
- Task & Channel → Logic Evaluation: evaluates rules · Inferred; not shown in the code that was read.
- Logic Evaluation → Alarm Records: raises alarms · Inferred; not shown in the code that was read.
- API Routes → Face Queries: routes queries · Inferred; not shown in the code that was read.
- Face Queries → Face Library: queries libraries (evidence: `src/api/MessageFaceLibHandler_Query.cc`)
- Face Queries → Person Persistence: queries people (evidence: `src/api/MessageFaceLibHandler_Query.cc`)
- Task & Channel → MQTT Client: delivers events · Inferred; not shown in the code that was read.
- Detection Pipeline → Inference Metrics: records metrics · Inferred; not shown in the code that was read.
- Video Ingest → Preview Metrics: records preview stats · Inferred; not shown in the code that was read.
- Storage Cleanup → Alarm Records: queries records (evidence: `src/service/infra/impl/StorageSpace.cc`)