# nkanyezingobese/ares_1 architecture

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

- Interactive diagram: https://gitdiagram.com/nkanyezingobese/ares_1
- Repository: https://github.com/nkanyezingobese/ares_1

## Overview

##### Project Type and Purpose
- Ares-1 is an open-source, local dev environment focused on streaming synthetic drilling telemetry, running a physics baseline, and placeholder ML anomaly detection.
- It is not a web front-end; rather, it is a data-streaming and processing pipeline with a visualization stub (Unity) and a configuration layer (Agents & Docs).

##### Top-Level Components (to show as distinct blocks)
a. Infrastructure
- MQTT Broker (Mosquitto, Docker Compose)
- Virtual environment (.venv) and Python runtime
b. Data Publisher
- Excel metrics (“Ares-1 terrain metrics.xlsx”)
- Karoo Telemetry Publisher (`python/ares1/telemetry/ares_karoo_publisher.py`)
- Publishing script (`python/scripts/publish_telemetry.py`)
c. Data Consumers & Processors
- Telemetry Subscriber (`python/scripts/subscribe_telemetry.py`)
- Event Subscriber (`python/scripts/subscribe_events.py`)
- Anomaly Detector (`python/scripts/run_anomaly_detector.py`)
- ML stub (`python/ares1/ml/anomaly.py`)
- Physics baseline (`python/ares1/physics/torque_drag.py`)
d. Persistence
- Outputs folder (CSV, JSON, JSONL logs)
e. Visualization Stub
- Unity project (`unity/ares1_unity_project/Ares-1`)
- MQTT bridge scripts (`Assets/Ares1/Scripts/*MqttTopicMap.cs`)
- UI scripts (TelemetryWidget, UdpTelemetryReceiver, etc.)
f. Configuration & Documentation
- Agents context (mission_context.md)
- Engineering docs (docs/architecture, grounding templates, planned data flow)

##### Relationships & Data Flows
- Telemetry Publisher → MQTT Broker (“telemetry” topic)
- MQTT Broker → Telemetry Subscriber → Outputs/telemetry_log.csv & telemetry_latest.json
- MQTT Broker → Anomaly Detector → processes physics & ML → publishes anomaly events to “events” topic
- MQTT Broker → Event Subscriber → Outputs/events_log.jsonl
- MQTT Broker → Unity MQTT bridge → real-time visualization in Unity
- Excel metrics → Karoo Publisher script → feeds Telemetry Publisher
- .env & requirements ensure correct configuration and dependencies

##### Key Architectural Patterns
- Pub/Sub messaging via MQTT for loose-coupling
- Modular Python scripts for each processing stage
- Clear separation: Data ingestion, processing, persistence, visualization
- Extensibility points: add new ML modules in `python/ares1/ml`, new physics baselines in `python/ares1/physics`, new Unity visualizations

##### Detailed Capture
- Docker-Compose file under MQTT block.
- Venv and requirements under Python runtime block.
- Call out that `agents/` and `docs/` are the single source of truth for mission context and architecture.

- Excel metrics → Karoo Publisher → Python Telemetry Publisher → MQTT Broker
- MQTT Broker → { Telemetry Subscriber → CSV/JSON ; Event Subscriber → JSONL ; Anomaly Detector → processing & publishes back to Broker }
- MQTT Broker → Unity client for visualization
- Config & Docs feeding mission context into scripts

This level of detail ensures every architectural element and data flow in Ares-1 is visible at a glance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "Infrastructure"
        style Infra fill:#a2f5a2,stroke:#2d7c2d,stroke-width:2px
        Infra_MQTT["MQTT Broker\n(Docker Compose)"]:::infra
        Infra_Python["Python Runtime\n(.venv, requirements)"]:::infra
    end

    subgraph "Data Publisher"
        style Publisher fill:#a2d2f5,stroke:#175481,stroke-width:2px
        Excel["Ares-1 terrain metrics.xlsx"]:::producer
        KarooPub["Karoo Telemetry Publisher"]:::producer
        PublishScript["publish_telemetry.py"]:::producer
    end

    subgraph "Data Consumers & Processors"
        style Consumer fill:#f5b37d,stroke:#a65d2d,stroke-width:2px
        TelemetrySub["subscribe_telemetry.py"]:::consumer
        EventSub["subscribe_events.py"]:::consumer
        AnomalyRun["run_anomaly_detector.py"]:::consumer
        subgraph "Anomaly Detector Modules"
            MLStub["anomaly.py"]:::consumer
            PhysicsBaseline["torque_drag.py"]:::consumer
        end
    end

    subgraph "Persistence"
        style Persist fill:#d7a2f5,stroke:#6d2d7c,stroke-width:2px
        Outputs["Outputs Folder\n(CSV, JSON, JSONL)"]:::persist
    end

    subgraph "Visualization Stub"
        style Viz fill:#a2f5ee,stroke:#2d7c68,stroke-width:2px
        UnityBridge["Unity MQTT Bridge\n(MqttTopicMap.cs)"]:::viz
        UnityUI["Unity UI Scripts"]:::viz
    end

    subgraph "Config & Documentation"
        style Config fill:#e0e0e0,stroke:#7a7a7a,stroke-width:2px,stroke-dasharray: 5 5
        AgentsCtx["mission_context.md"]:::config
        ArchDocs["system_overview.md\nphysics_baseline.md"]:::config
        FlowDocs["planned_data_flow.md"]:::config
    end

    %% Data Flows
    Excel -->|feeds metrics| KarooPub
    KarooPub -->|generates telemetry| PublishScript
    PublishScript -->|“telemetry”| Infra_MQTT
    Infra_MQTT -->|“telemetry”| TelemetrySub
    TelemetrySub -->|writes CSV/JSON| Outputs
    Infra_MQTT -->|“telemetry”| UnityBridge
    UnityBridge -->|updates UI| UnityUI
    Infra_MQTT -->|“telemetry”| AnomalyRun
    AnomalyRun -->|uses| MLStub
    AnomalyRun -->|uses| PhysicsBaseline
    AnomalyRun -->|“events”| Infra_MQTT
    Infra_MQTT -->|“events”| EventSub
    EventSub -->|writes JSONL| Outputs

    %% Config & Docs Relationships (dashed)
    AgentsCtx -.-> PublishScript
    AgentsCtx -.-> TelemetrySub
    ArchDocs -.-> PhysicsBaseline
    FlowDocs -.-> PublishScript

    %% Click Events
    click Infra_MQTT "https://github.com/nkanyezingobese/ares_1/blob/main/mqtt/docker-compose.yml"
    click Infra_MQTT "https://github.com/nkanyezingobese/ares_1/blob/main/mqtt/mosquitto.conf"
    click Infra_Python "https://github.com/nkanyezingobese/ares_1/blob/main/python/pyproject.toml"
    click Infra_Python "https://github.com/nkanyezingobese/ares_1/blob/main/python/requirements.txt"
    click Excel "https://github.com/nkanyezingobese/ares_1/blob/main/Ares-1 terrain metrics.xlsx"
    click KarooPub "https://github.com/nkanyezingobese/ares_1/blob/main/python/ares1/telemetry/ares_karoo_publisher.py"
    click PublishScript "https://github.com/nkanyezingobese/ares_1/blob/main/python/scripts/publish_telemetry.py"
    click TelemetrySub "https://github.com/nkanyezingobese/ares_1/blob/main/python/scripts/subscribe_telemetry.py"
    click EventSub "https://github.com/nkanyezingobese/ares_1/blob/main/python/scripts/subscribe_events.py"
    click AnomalyRun "https://github.com/nkanyezingobese/ares_1/blob/main/python/scripts/run_anomaly_detector.py"
    click MLStub "https://github.com/nkanyezingobese/ares_1/blob/main/python/ares1/ml/anomaly.py"
    click PhysicsBaseline "https://github.com/nkanyezingobese/ares_1/blob/main/python/ares1/physics/torque_drag.py"
    click UnityBridge "https://github.com/nkanyezingobese/ares_1/blob/main/unity/ares1_unity_project/Ares-1/Assets/Ares1/Scripts/MqttTopicMap.cs"
    click UnityUI "https://github.com/nkanyezingobese/ares_1/blob/main/unity/ares1_unity_project/Ares-1/Assets/UI/Scripts/*.cs"
    click AgentsCtx "https://github.com/nkanyezingobese/ares_1/blob/main/agents/context/mission_context.md"
    click ArchDocs "https://github.com/nkanyezingobese/ares_1/blob/main/docs/architecture/system_overview.md"
    click ArchDocs "https://github.com/nkanyezingobese/ares_1/blob/main/docs/architecture/physics_baseline.md"
    click FlowDocs "https://github.com/nkanyezingobese/ares_1/blob/main/docs/planned_data_flow.md"

    %% Styles
    classDef infra fill:#a2f5a2,stroke:#2d7c2d;
    classDef producer fill:#a2d2f5,stroke:#175481;
    classDef consumer fill:#f5b37d,stroke:#a65d2d;
    classDef persist fill:#d7a2f5,stroke:#6d2d7c;
    classDef viz fill:#a2f5ee,stroke:#2d7c68;
    classDef config fill:#e0e0e0,stroke:#7a7a7a,stroke-dasharray: 5 5;
```
