%% View 1 — System topology.
%% Runtime processes and external systems, with process boundaries drawn explicitly.
%% mavend is the centre because the code makes it one: it is the only key holder,
%% it owns the store, the IPC socket, the voice listener, the tick loop, eight
%% in-process background workers and the child llama-server.
%% Evidence: docker-compose.yml, cmd/mavend/main.go, cmd/mavend/boot.go,
%% deploy/mavwaked.service, deploy/mavgpud.service.
flowchart LR

  subgraph WORKPC["workpc — systemd user units, never in docker-compose"]
    direction TB
    MAVWAKED["mavwaked<br/>process<br/>arecord · silero VAD · keyword head"]
    MAVGPUD["mavgpud<br/>process<br/>GPU supervisor"]
    LLAMA_W["llama-server<br/>model · workstation card"]
    CW2["CrisperWhisper2 turbo<br/>model · port 8081"]
    ALSA["arecord / aplay<br/>external"]
    TUNNEL["maven-voice-tunnel.service<br/>ssh · the only path in"]
  end

  subgraph HOMESRV["homesrv — docker compose project `maven`"]
    direction TB

    subgraph MAVEND_P["mavend — process boundary · the only key holder"]
      direction TB
      IPCSRV["IPC server<br/>unix /run/maven/mavend.sock"]
      VOICESRV["voice server<br/>TCP 0.0.0.0:9100"]
      TURN["reactive handler<br/>the turn pipeline"]
      TICK["tick loop<br/>60s"]
      WORKERS["8 background workers<br/>tick · fact-enrichment · feed · crawl<br/>voice · mcp · home · memory-eval"]
      STORE[("store<br/>sqlite, MaxOpenConns=1")]
    end

    LLAMA_H["llama-server<br/>model · resident<br/>child process of mavend"]
    MAVSTTD["mavsttd<br/>process<br/>whisper.cpp"]
    MAVTTSD["mavttsd<br/>process<br/>piper"]
    MAVWEB["mavweb<br/>process<br/>HTTP 127.0.0.1:9201"]
    MAVPOLL["mavpoll<br/>process<br/>network_mode: host"]
    SEARX["SearXNG<br/>external"]
    KIWIX["kiwix-server<br/>external"]
    NETDATA["netdata<br/>external"]
    KUMA["uptime-kuma<br/>external"]
  end

  subgraph OFF["built, not deployed — commented out in docker-compose.yml"]
    direction TB
    MAVCALDAV["mavcaldav<br/>process"]
    MAVMAILD["mavmaild<br/>process"]
  end

  subgraph ECO["ecosystem network — external compose project"]
    direction TB
    NEXUS["Nexus<br/>external · identity"]
    PRAXIS["Praxis<br/>external · attention"]
    HEXIS["Hexis<br/>external · capabilities"]
  end

  subgraph NET["internet"]
    direction TB
    TG["Telegram Bot API<br/>external · via SOCKS relay"]
    NTFY["ntfy<br/>external · DISABLED in config"]
    ZM["zenmoney<br/>external · no token mounted"]
  end

  HA["Home Assistant<br/>external · enabled:false"]

  %% ---- voice path
  ALSA --- MAVWAKED
  MAVWAKED -->|"PushToTalk · TCP"| TUNNEL
  TUNNEL -->|"ssh to 127.0.0.1:9110"| VOICESRV
  VOICESRV -->|"proactive Push on the same conn"| MAVWAKED

  %% ---- module IPC
  MAVWEB -->|"3 × ipc.Client · unix"| IPCSRV
  MAVWEB -->|"POST /api/ptt · TCP mavend:9100"| VOICESRV
  MAVPOLL -->|"WriteFact · unix"| IPCSRV
  MAVCALDAV -.->|"WriteFact · unix"| IPCSRV
  MAVMAILD -.->|"IngestMail · unix"| IPCSRV

  %% ---- worker sockets
  TURN -->|"worker · unix stt.sock"| MAVSTTD
  TURN -->|"worker · unix tts.sock"| MAVTTSD
  TURN -->|"HTTP · preferred, silent fallback"| CW2

  %% ---- models
  MAVEND_P ---|"spawns and owns"| LLAMA_H
  MAVGPUD ---|"spawns and supervises"| LLAMA_W
  MAVGPUD ---|"spawns and supervises"| CW2
  TURN -.->|"llm.Pair · model_disabled:true"| MAVGPUD

  %% ---- world and ecosystem
  TURN -->|"HTTP · query string only"| SEARX
  TURN -->|"HTTP"| KIWIX
  TURN -->|"HTTP · v1 contract, correlation id"| NEXUS
  TURN -->|"HTTP"| PRAXIS
  TURN -->|"HTTP"| HEXIS
  MAVWEB -->|"HTTP · read-only panel"| NEXUS
  MAVWEB -->|"HTTP · read-only panel"| PRAXIS
  MAVWEB -->|"HTTP · read-only panel"| HEXIS
  TURN -.->|"HTTP · enabled:false"| HA

  %% ---- reaches
  TICK -->|"telegram sink"| TG
  TG -->|"getUpdates long poll"| TURN
  TICK -.->|"ntfy sink · nil, disabled"| NTFY

  %% ---- pollers
  MAVPOLL --> NETDATA
  MAVPOLL --> KUMA
  MAVPOLL -.-> ZM

  classDef proc fill:#1f3a5f,stroke:#7fb3ff,color:#eaf2ff
  classDef ext fill:#3d2f4f,stroke:#c39bd3,color:#f4ecf7
  classDef model fill:#4a3a1f,stroke:#e0b050,color:#fff6e0
  classDef store fill:#1f4a3a,stroke:#6ed0a8,color:#e8fff5
  classDef off fill:#3a3a3a,stroke:#888,color:#ccc,stroke-dasharray:4 3
  class MAVWAKED,MAVGPUD,MAVSTTD,MAVTTSD,MAVWEB,MAVPOLL,IPCSRV,VOICESRV,TURN,TICK,WORKERS proc
  class ALSA,SEARX,KIWIX,NETDATA,KUMA,NEXUS,PRAXIS,HEXIS,TG,TUNNEL ext
  class LLAMA_H,LLAMA_W,CW2 model
  class STORE store
  class MAVCALDAV,MAVMAILD,NTFY,ZM,HA off