Complete System Data Flow Diagram

flowchart TB
    subgraph Sensors["📡 Physical Sensors"]
        Mocopi[Mocopi Sensor<br/>50Hz UDP<br/>26 bones + quaternions]
        Kinect[Kinect v2<br/>30Hz USB<br/>25 joints + depth]
    end

    subgraph Relay["🔄 Mocopi Relay (Rust)"]
        UDP[UDP Receiver<br/>Port 9090]
        Validate[Validate + Parse<br/>CRC32 check]
        HMAC[Compute HMAC-SHA256<br/>Attach signature]
    end

    subgraph Echelon["🎵 Echelon Real-Time Core (Rust)"]
        Motion[Motion Capture Thread<br/>Priority 95<br/>60Hz processing]
        EKF_Thread[Anticipation Thread<br/>Priority 90<br/>Extended Kalman Filter]
        Audio[Audio Thread<br/>Priority 99<br/>48kHz synthesis]

        DELL[DELL Neural Network<br/>Fast eq: 60Hz<br/>Slow eq: 2.5Hz]
        PM[Physical Modeling<br/>Clarinet synthesis<br/>512 samples/buffer]
    end

    subgraph Buffers["🔗 Lock-Free Queues"]
        Q1[Motion → EKF<br/>SPSC Ringbuffer<br/>128 frames]
        Q2[EKF → Audio<br/>SPSC Ringbuffer<br/>64 states]
        Q3[Motion → Sync<br/>Aggregation buffer<br/>64 segments]
    end

    subgraph Sync["⏱️ Sync Thread (0.2Hz)"]
        Timer[Wakeup every 5s]
        Aggregate[Aggregate segments<br/>Compute statistics]
        FFI[FFI Call to Python<br/>PyO3 boundary]
    end

    subgraph Python["🐍 TrajectoryOS (Python)"]
        RAG[RAG++ Service<br/>FastAPI + HNSW]
        Orbit[Orbit Memory<br/>PostgreSQL + 5D index]

        Map5D[Map to 5D Coords<br/>Temporal, Semantic, Depth, Homogeneity, Salience]
        HNSW[HNSW Search<br/>Find K=10 neighbors]
        IRCP[I-RCP Propagation<br/>Attention routing]
        StyleUpdate[Update Style Signature<br/>DELL slow equilibrium]
    end

    subgraph Storage["💾 Persistent Storage"]
        Supabase[Supabase PostgreSQL<br/>• User accounts<br/>• Session metadata<br/>• Trajectory turns]
        GCS[Google Cloud Storage<br/>• Raw mocopi recordings<br/>• Audio exports<br/>• Model checkpoints]
    end

    subgraph UI["🖥️ User Interface"]
        Tauri[Tauri Desktop App<br/>React 19 + TypeScript]
        Viz[Real-Time Visualization<br/>3D skeleton + waveform]
        Controls[Playback Controls<br/>Record, export, analyze]
    end

    %% Sensor → Relay
    Mocopi -->|UDP packets| UDP
    Kinect -->|USB frames| Motion

    %% Relay → Echelon
    UDP --> Validate --> HMAC
    HMAC -->|Verified frames| Motion

    %% Echelon internal flow
    Motion -->|Raw frames| Q1
    Q1 -->|Latest frame| EKF_Thread
    EKF_Thread -->|Anticipation state| Q2
    Q2 -->|Latest state| Audio

    Motion -->|Completed segments| Q3
    Q3 -->|Batch read| Timer

    %% Audio synthesis
    Audio -->|Motion + Style| DELL
    DELL -->|Audio params| PM
    PM -->|PCM samples| Viz
    PM -.->|Audio stream| Speakers[🔊 Audio Output]

    %% Sync → Python
    Timer --> Aggregate --> FFI
    FFI -->|TrajectorySegment| Map5D

    %% Python processing
    Map5D -->|Trajectory5D| HNSW
    HNSW -->|Neighbors| IRCP
    IRCP -->|Updated memory| Orbit
    Orbit -->|Store turn| Supabase

    %% Style feedback
    IRCP --> StyleUpdate
    StyleUpdate -->|New style signature| FFI
    FFI -->|Return to Rust| Audio

    %% UI interactions
    Tauri -->|Control commands| Echelon
    Tauri -->|Query sessions| Supabase
    Tauri -->|Fetch trajectories| RAG
    Viz -->|Display| Tauri
    Controls -->|User actions| Tauri

    %% Export paths
    Echelon -.->|Record session| GCS
    Tauri -.->|Export audio| GCS

    style Sensors fill:#ffe0b2
    style Relay fill:#fff9c4
    style Echelon fill:#ffcdd2
    style Buffers fill:#e1bee7
    style Sync fill:#c5cae9
    style Python fill:#b2dfdb
    style Storage fill:#c8e6c9
    style UI fill:#bbdefb

graph LR
    subgraph T1["Transform 1:<br/>Sensor → Validated Frame"]
        Input1[Raw UDP/USB<br/>Binary blob<br/>~800 bytes]
        Process1[• Parse binary<br/>• Validate checksum<br/>• Range check<br/>• Add HMAC]
        Output1[MocopiFrame<br/>26 bones<br/>Verified]

        Input1 --> Process1 --> Output1
    end

    subgraph T2["Transform 2:<br/>Frame → Anticipation"]
        Input2[Motion Frame<br/>Position + velocity<br/>6-DOF per bone]
        Process2[• EKF prediction<br/>• Covariance update<br/>• Gesture detection]
        Output2[AnticipationState<br/>x̂, P, commitment<br/>3D vector + scalar]

        Input2 --> Process2 --> Output2
    end

    subgraph T3["Transform 3:<br/>Segment → 5D Trajectory"]
        Input3[TrajectorySegment<br/>• Duration<br/>• Gesture type<br/>• Statistics<br/>• Style signature]
        Process3[• Temporal: normalize<br/>• Semantic: encode gesture<br/>• Depth: always 0<br/>• Homogeneity: stability<br/>• Salience: commitment]
        Output3[Trajectory5D<br/>5 floats ∈ 0,1<br/>Ready for HNSW]

        Input3 --> Process3 --> Output3
    end

    subgraph T4["Transform 4:<br/>5D → Memory Turn"]
        Input4[Trajectory5D<br/>+ Context]
        Process4[• HNSW search<br/>• Find K=10 neighbors<br/>• I-RCP propagation<br/>• Compute admissibility]
        Output4[MemoryTurn<br/>turn_id<br/>Stored in Orbit]

        Input4 --> Process4 --> Output4
    end

    subgraph T5["Transform 5:<br/>Memory → Style"]
        Input5[Local Neighborhood<br/>K nearest turns]
        Process5[• Aggregate embeddings<br/>• DELL slow eq<br/>• Weight interpolation]
        Output5[StyleSignature<br/>256-dim vector<br/>Audio influence]

        Input5 --> Process5 --> Output5
    end

    subgraph T6["Transform 6:<br/>Style → Audio"]
        Input6[Motion + Style + Commitment]
        Process6[• DELL inference<br/>• Gating network<br/>• Output projection]
        Output6[Audio Parameters<br/>32-dim<br/>FM + ADSR + reverb]

        Input6 --> Process6 --> Output6
    end

    subgraph T7["Transform 7:<br/>Params → Sound"]
        Input7[Audio Parameters]
        Process7[• Physical modeling<br/>• Clarinet synthesis<br/>• 512 samples]
        Output7[PCM Audio<br/>48kHz stereo<br/>f32 samples]

        Input7 --> Process7 --> Output7
    end

    T1 --> T2 --> T3 --> T4 --> T5 --> T6 --> T7

    style T1 fill:#ffecb3
    style T2 fill:#ffe0b2
    style T3 fill:#ffcc80
    style T4 fill:#ffb74d
    style T5 fill:#ffa726
    style T6 fill:#ff9800
    style T7 fill:#fb8c00

gantt
    title Critical Path Latency (Sensor to Audio Output)
    dateFormat SSS
    axisFormat %L ms

    section Sensor Input
    Mocopi capture (50Hz)           :000, 20ms
    UDP transmission                :020, 2ms

    section Mocopi Relay
    Packet receive + parse          :022, 1ms
    HMAC computation                :023, 1ms

    section Echelon Motion
    Queue write (lock-free)         :024, 0.01ms
    Motion processing               :024, 1ms

    section Echelon EKF
    Queue read (lock-free)          :025, 0.01ms
    EKF update                      :025, 2ms
    Gesture detection               :027, 1ms

    section Echelon Audio
    Queue read (lock-free)          :028, 0.01ms
    DELL inference                  :028, 0.12ms
    PM synthesis (512 samples)      :028, 8ms
    Audio buffer write              :036, 0.5ms

    section Total Output
    Audio playback start            :036, 0ms

graph TB
    subgraph Hot["🔥 Hot Path (L1 Cache)"]
        H1[DELL weights<br/>674 KB<br/>Read-only]
        H2[Hidden states<br/>3 KB per instance<br/>Read-write]
        H3[Audio buffers<br/>4 KB per buffer<br/>Pre-allocated]
        H4[Style signature<br/>1 KB<br/>Atomic swap]
    end

    subgraph Warm["🌡️ Warm Path (L3 Cache / RAM)"]
        W1[SPSC queues<br/>~200 KB total<br/>Lock-free]
        W2[Mocopi frames<br/>128 frames × 1 KB<br/>Ringbuffer]
        W3[EKF state<br/>~10 KB<br/>Covariance matrices]
    end

    subgraph Cold["❄️ Cold Path (RAM / Disk)"]
        C1[Trajectory segments<br/>64 segments × 1 KB<br/>Infrequent access]
        C2[Session recordings<br/>~100 MB/hour<br/>Disk-backed]
        C3[HNSW index<br/>Varies with turns<br/>PostgreSQL]
    end

    Hot -.->|Cache miss| Warm
    Warm -.->|Page fault| Cold

    style Hot fill:#ffcdd2
    style Warm fill:#fff9c4
    style Cold fill:#c8e6c9

flowchart TD
    subgraph Transient["⚡ Transient (Lost on Restart)"]
        T1[SPSC queues<br/>In-memory only]
        T2[DELL hidden states<br/>Reset to zero]
        T3[Audio buffers<br/>Cleared]
    end

    subgraph Session["💾 Session-Scoped (Saved on Export)"]
        S1[Mocopi recording<br/>Binary file<br/>~100 MB/hour]
        S2[Audio rendering<br/>WAV export<br/>~50 MB/hour]
        S3[Session metadata<br/>JSON file<br/>~10 KB]
    end

    subgraph Persistent["🗄️ Persistent (Always Saved)"]
        P1[Trajectory turns<br/>PostgreSQL<br/>INSERT on ingest]
        P2[5D coordinates<br/>HNSW index<br/>Indexed]
        P3[User account<br/>Supabase Auth<br/>Managed]
        P4[Style signatures<br/>Versioned per turn<br/>Binary column]
    end

    Transient -.->|On user command| Session
    Session -.->|On ingestion| Persistent

    style Transient fill:#ffebee
    style Session fill:#fff9c4
    style Persistent fill:#c8e6c9

flowchart TD
    Start[Data enters system] --> Validate{Validation<br/>successful?}

    Validate -->|No| Log[Log error<br/>Increment metric]
    Log --> Drop[Drop data<br/>Continue processing]

    Validate -->|Yes| Process[Process data]

    Process --> Check{Critical<br/>invariant<br/>violated?}

    Check -->|Yes| Panic[Thread panic<br/>Supervisor restart]
    Panic --> Recover[Recover to last<br/>known-good state]
    Recover --> Alert[Send alert<br/>PagerDuty]

    Check -->|No| Success{Processing<br/>successful?}

    Success -->|No| Retry{Retriable<br/>error?}

    Retry -->|Yes| Backoff[Exponential backoff<br/>Max 3 retries]
    Backoff --> Process

    Retry -->|No| Circuit{Circuit breaker<br/>open?}

    Circuit -->|Yes| Degrade[Degrade gracefully<br/>Use cached value]
    Circuit -->|No| OpenCircuit[Open circuit<br/>Fail fast]

    Success -->|Yes| Forward[Forward to next stage]

    Drop --> End([Continue])
    Degrade --> End
    OpenCircuit --> End
    Forward --> End
    Alert -.-> End

    style Panic fill:#ff5252
    style OpenCircuit fill:#ff7043
    style Degrade fill:#ffa726
    style Success fill:#66bb6a

graph LR
    subgraph Input["Input Metrics"]
        I1[cc_mocopi_frames_received_total<br/>Counter]
        I2[cc_mocopi_parse_duration_seconds<br/>Histogram]
        I3[cc_frames_dropped_total<br/>Counter by reason]
    end

    subgraph Processing["Processing Metrics"]
        P1[cc_ekf_update_duration_seconds<br/>Histogram]
        P2[cc_dell_inference_duration_seconds<br/>Histogram]
        P3[cc_pm_synthesis_duration_seconds<br/>Histogram]
    end

    subgraph Output["Output Metrics"]
        O1[cc_audio_frames_rendered_total<br/>Counter]
        O2[cc_audio_underruns_total<br/>Counter]
        O3[cc_trajectory_turns_ingested_total<br/>Counter]
    end

    subgraph Derived["Derived Metrics (PromQL)"]
        D1["Frame drop rate:<br/>rate(cc_frames_dropped_total[1m]) /<br/>rate(cc_mocopi_frames_received_total[1m])"]

        D2["Audio latency P99:<br/>histogram_quantile(0.99,<br/>rate(cc_pm_synthesis_duration_seconds_bucket[5m]))"]

        D3["Ingestion throughput:<br/>rate(cc_trajectory_turns_ingested_total[5m]) * 60"]
    end

    Input --> Processing --> Output
    Output --> Derived

    style Input fill:#e3f2fd
    style Processing fill:#fff3e0
    style Output fill:#e8f5e9
    style Derived fill:#f3e5f5

stateDiagram-v2
    [*] --> Idle: App launched

    Idle --> Connecting: User clicks "Connect Mocopi"

    Connecting --> Connected: UDP packets received
    Connecting --> Error: Timeout (10s)

    Connected --> Recording: User clicks "Record"

    Recording --> Paused: User clicks "Pause"
    Paused --> Recording: User clicks "Resume"

    Recording --> Processing: User clicks "Stop"

    Processing --> Uploading: Trajectory segments finalized
    note right of Processing
        • Aggregate statistics
        • Compute final style signature
        • Generate session metadata
    end note

    Uploading --> Complete: Supabase insert successful
    Uploading --> UploadError: Network error

    UploadError --> Retry: Auto-retry (max 3)
    Retry --> Uploading

    UploadError --> SavedLocally: Max retries exceeded
    note right of SavedLocally
        • Save to local SQLite
        • Queue for background upload
        • User can continue
    end note

    Complete --> Idle: Return to idle
    SavedLocally --> Idle

    Error --> Idle: Reset connection

    Connected --> Idle: User disconnects

sequenceDiagram
    participant Tauri as Tauri App
    participant Echelon as Echelon (Local)
    participant Relay as Mocopi Relay
    participant CloudRun as Cloud Run Services
    participant Supabase as Supabase

    %% Session start
    Tauri->>Supabase: Authenticate (JWT)
    Supabase-->>Tauri: Session token

    Tauri->>Relay: Start mocopi capture
    Relay->>Relay: Bind UDP :9090

    %% Real-time loop
    loop Every 20ms (50Hz)
        Relay->>Echelon: Send validated frame<br/>(SPSC queue)
        Echelon->>Echelon: Process motion<br/>Synthesize audio
    end

    %% Periodic sync
    loop Every 5s (0.2Hz)
        Echelon->>CloudRun: POST /trajectories/ingest<br/>TrajectorySegment + JWT
        CloudRun->>CloudRun: Verify JWT
        CloudRun->>CloudRun: Map to 5D coords
        CloudRun->>Supabase: INSERT trajectory turn
        Supabase-->>CloudRun: turn_id
        CloudRun-->>Echelon: StyleSignature
        Echelon->>Echelon: Update DELL weights
    end

    %% Session end
    Tauri->>Echelon: Stop recording
    Echelon->>Echelon: Finalize session
    Echelon->>Tauri: Session summary
    Tauri->>CloudRun: POST /sessions/complete<br/>Metadata + JWT
    CloudRun->>Supabase: UPDATE session status