detections-semantic/_docs/02_plans/diagrams/components.md

Component Diagram — Semantic Detection System

graph TB
    subgraph External["External Systems"]
        YOLO["Existing YOLO Pipeline"]
        CAM["ViewPro A40 Camera"]
        GPS["GPS-Denied System"]
        OP["Operator Display"]
        NVME["NVMe Storage"]
    end

    subgraph Helpers["Common Helpers"]
        CFG["Config\n(YAML loader + validation)"]
        TYP["Types\n(shared dataclasses)"]
    end

    subgraph Core["Core Components"]
        SC["ScanController\n(py_trees BT orchestrator)"]
        T1["Tier1Detector\n(YOLOE TensorRT FP16)"]
        T2["Tier2SpatialAnalyzer\n(mask trace + cluster trace)"]
        VLM["VLMClient\n(NanoLLM IPC)"]
        GD["GimbalDriver\n(ViewLink + PID)"]
        OM["OutputManager\n(logging + recording)"]
    end

    subgraph VLMContainer["Docker Container"]
        NANO["NanoLLM\n(VILA1.5-3B)"]
    end

    %% Helper dependencies (all components use both)
    CFG -.-> T1
    CFG -.-> T2
    CFG -.-> VLM
    CFG -.-> GD
    CFG -.-> OM
    CFG -.-> SC
    TYP -.-> T1
    TYP -.-> T2
    TYP -.-> VLM
    TYP -.-> GD
    TYP -.-> OM
    TYP -.-> SC

    %% ScanController orchestrates all
    SC -->|"detect(frame)"| T1
    SC -->|"trace_mask / trace_cluster"| T2
    SC -->|"analyze(roi, prompt)"| VLM
    SC -->|"set_angles / follow_path / zoom_to_poi"| GD
    SC -->|"log_detection / record_frame"| OM

    %% VLM to NanoLLM container
    VLM -->|"Unix socket IPC"| NANO

    %% External integrations
    YOLO -->|"detections[]"| SC
    CAM -->|"HDMI/IP frames"| SC
    GD -->|"UART ViewLink"| CAM
    OM -->|"YOLO format output"| OP
    OM -->|"JPEG + JSON-lines"| NVME
    GPS -.->|"coordinates (optional)"| OM

    %% Styling
    classDef external fill:#f0f0f0,stroke:#999,color:#333
    classDef helper fill:#e8f4fd,stroke:#4a90d9,color:#333
    classDef core fill:#d4edda,stroke:#28a745,color:#333
    classDef container fill:#fff3cd,stroke:#ffc107,color:#333

    class YOLO,CAM,GPS,OP,NVME external
    class CFG,TYP helper
    class SC,T1,T2,VLM,GD,OM core
    class NANO container

Component Dependency Graph (implementation order)

graph LR
    CFG["Config"] --> T1["Tier1Detector"]
    CFG --> T2["Tier2SpatialAnalyzer"]
    CFG --> VLM["VLMClient"]
    CFG --> GD["GimbalDriver"]
    CFG --> OM["OutputManager"]
    TYP["Types"] --> T1
    TYP --> T2
    TYP --> VLM
    TYP --> GD
    TYP --> OM

    T1 --> SC["ScanController"]
    T2 --> SC
    VLM --> SC
    GD --> SC
    OM --> SC

    SC --> IT["Integration Tests"]

Data Flow Summary

flowchart LR
    Frame["Camera Frame"] --> T1["Tier1\nYOLOE detect"]
    T1 -->|"detections[]"| Eval["EvaluatePOI\n(scenario match)"]
    Eval -->|"POI queued"| L2["L2 Investigation"]
    L2 -->|"mask"| T2M["Tier2\ntrace_mask"]
    L2 -->|"cluster dets"| T2C["Tier2\ntrace_cluster"]
    T2M -->|"waypoints"| Follow["Gimbal\nPID follow"]
    T2C -->|"waypoints"| Visit["Gimbal\nvisit loop"]
    Follow -->|"ambiguous"| VLM["VLM\nanalyze"]
    Visit -->|"ambiguous"| VLM
    Follow -->|"detection"| Log["OutputManager\nlog + record"]
    Visit -->|"detection"| Log
    VLM -->|"tier3 result"| Log
    Log -->|"operator format"| OP["Operator Display"]
    Log -->|"JPEG + JSON"| NVME["NVMe Storage"]