Diagrams

Status: living

These diagrams use a C4-inspired structure plus state/runtime views.

System Context

flowchart LR
    Operator[Local operator]
    Host[Dubnium NixOS host]
    GPUs[Display and compute GPUs]
    Audio[Audio interface]
    Studio[Optional external studio host]
    Micrantha[Micrantha / k3s workloads]
    Models[Local model bundles / runtime data]

    Operator -->|mode request/status| Host
    Host --> GPUs
    Host --> Audio
    Host -->|future placement| Studio
    Host --> Micrantha
    Host --> Models

Container View

flowchart TD
    CLI[mode CLI]
    Controller[mode-controller]
    Observer[observe-current]
    Guards[guard scripts]
    Systemd["systemd targets/services/slices"]
    Workloads["Hyprland, audio, vLLM, k3s"]
    Runtime["/run/mode-controller"]
    Audit["/var/lib/mode-controller"]

    CLI --> Runtime
    CLI --> Controller
    Controller --> Observer
    Controller --> Guards
    Controller --> Systemd
    Systemd --> Workloads
    Observer --> Systemd
    Observer --> Runtime
    Controller --> Runtime
    Controller --> Audit

Mode State View

stateDiagram-v2
    [*] --> bootstrapping
    bootstrapping --> desktop: boot default

    desktop --> studioLocal: request studio-local
    studioLocal --> desktop: request desktop

    desktop --> transitioning: request compute
    compute --> transitioning: request desktop

    transitioning --> desktop: observed desktop
    transitioning --> compute: observed compute
    transitioning --> studioLocal: observed studio-local
    transitioning --> degradedDesktop: partial desktop
    transitioning --> degradedCompute: partial compute
    transitioning --> failedTransition: unsafe/conflicted

    degradedDesktop --> desktop: reconcile
    degradedCompute --> compute: reconcile
    failedTransition --> desktop: rollback succeeds

Reconciliation Sequence

sequenceDiagram
    participant U as Operator
    participant C as mode CLI
    participant R as Reconciler
    participant O as Observer
    participant G as Guards
    participant S as systemd

    U->>C: mode request compute
    C->>R: start mode-controller@compute
    R->>R: acquire lock
    R->>O: observe current
    O-->>R: desktop with evidence
    R->>G: run transition guards
    G-->>R: pass/block/error results
    R->>S: terminate session / isolate target / start services
    R->>O: re-observe
    O-->>R: compute or degraded/failed
    R-->>C: transition result
    C-->>U: status