update docs

2026-05-06 11:51:43 -03:00
parent c8bb6c7581
commit 946234eb9e
16 changed files with 1723 additions and 502 deletions
--- a/docs/graphs/system.dot
+++ b/docs/graphs/system.dot
@@ -0,0 +1,77 @@
+// Mitus — top-level architecture
+// Sender (Wayland, VAAPI) → network → Receiver (X11, NVDEC/NVENC) → Mitus GUI app
+// Two transport modes share the same recording layout and same GUI.
+digraph system {
+    graph [fontname="monospace" bgcolor="#1e1e2e" rankdir=LR pad="0.6" splines=polyline nodesep=0.5 ranksep=0.8]
+    node  [fontname="monospace" fontcolor="#cdd6f4" style=filled shape=box
+           fillcolor="#313244" color="#585b70" margin="0.25,0.14"]
+    edge  [color="#585b70" fontname="monospace" fontcolor="#a6adc8"]
+
+    subgraph cluster_sender {
+        label="Sender machine — Wayland, VAAPI GPU" fontcolor="#a6adc8" color="#45475a" fontname="monospace"
+
+        capture_py [label="kmsgrab + PulseAudio\n─────────────\nsender/stream_av.sh\nffmpeg CLI · h264_vaapi · AAC\nmpegts over TCP" fillcolor="#2d2038" color="#cba6f7"]
+
+        capture_rs [label="cht-client (Rust)\n─────────────\nmedia/client/\nffmpeg subprocess (subprocess backend)\nNUT demux → mpsc → WirePacket TCP" fillcolor="#1e2d3e" color="#89b4fa"]
+    }
+
+    subgraph cluster_net {
+        label="Network" fontcolor="#a6adc8" color="#45475a" fontname="monospace"
+        net_py [label="TCP :4444\nmpegts" shape=parallelogram fillcolor="#1e2a3e" color="#89b4fa"]
+        net_rs [label="TCP :4447\nWirePacket framing" shape=parallelogram fillcolor="#1e2a3e" color="#89b4fa"]
+    }
+
+    subgraph cluster_receiver {
+        label="Receiver (mcrn) — X11, NVENC/NVDEC GPU" fontcolor="#a6adc8" color="#45475a" fontname="monospace"
+
+        recorder_py [label="StreamRecorder (Python)\n─────────────\ncht/stream/recorder.py\nffmpeg listener · TCP receive\nfMP4 writer · UDP relay\nstdout-pipe scene detect"
+                     fillcolor="#2d2038" color="#cba6f7"]
+
+        recorder_rs [label="cht-server (Rust)\n─────────────\nmedia/server/\nWirePacket router\nfMP4 + UDP relay (ffmpeg)\nADTS audio writer\nUnix-socket scene relay"
+                     fillcolor="#1e2d3e" color="#89b4fa"]
+
+        processor [label="SessionProcessor (Python)\n─────────────\ncht/stream/processor.py\nfMP4 → audio.wav (ffmpeg)\nchunked WAVs for transcribe\n[Rust mode: scene detect via\nUnix socket → ffmpeg pipe]"
+                   fillcolor="#2d2038" color="#cba6f7"]
+
+        transcriber [label="Transcriber\n─────────────\ncht/transcriber/engine.py\nfaster-whisper · CUDA\nsegment grouping"
+                     fillcolor="#2d2038" color="#cba6f7"]
+
+        gui [label="Mitus GUI (GTK4 + libadwaita)\n─────────────\ncht/window.py · cht/ui/*\nMonitor (mpv UDP) · Scrub bar\nFrames panel · Transcript panel\nAgent input/output"
+             fillcolor="#2d2038" color="#cba6f7"]
+
+        agent [label="Agent runner\n─────────────\ncht/agent/*\nClaude SDK · OpenAI/Groq\n@F frame refs · @T transcript refs"
+               fillcolor="#2d2038" color="#cba6f7"]
+
+        store [label="data/<session_id>/\n─────────────\nstream/recording_*.mp4\nstream/audio.aac (Rust mode)\nframes/*.jpg + index.json\naudio/chunk_*.wav\ntranscript.json · thread.json"
+               shape=folder fillcolor="#2a2a3e" color="#585b70"]
+    }
+
+    // Python transport flow
+    capture_py -> net_py [color="#cba6f7"]
+    net_py -> recorder_py [color="#cba6f7"]
+    recorder_py -> store [color="#cba6f7"]
+    recorder_py -> processor [label="raw scene\nframes" color="#cba6f7"]
+
+    // Rust transport flow
+    capture_rs -> net_rs [color="#89b4fa"]
+    net_rs -> recorder_rs [color="#89b4fa"]
+    recorder_rs -> store [color="#89b4fa"]
+    recorder_rs -> processor [label="scene.sock\n(H.264)" style=dashed color="#a6e3a1"]
+
+    // Shared downstream
+    store -> processor [style=dashed]
+    processor -> transcriber [label="WAV chunks"]
+    transcriber -> store [label="transcript.json"]
+    store -> gui [label="files + watchers"]
+    gui -> agent [label="@-mentions"]
+    agent -> store [label="thread.json" style=dashed]
+
+    // Legend
+    subgraph cluster_legend {
+        label="Legend" fontcolor="#a6adc8" color="#585b70" fontname="monospace"
+        l_py [label="Python" fillcolor="#2d2038" color="#cba6f7"]
+        l_rs [label="Rust"   fillcolor="#1e2d3e" color="#89b4fa"]
+        l_io [label="I/O · network" shape=parallelogram fillcolor="#1e2a3e" color="#89b4fa"]
+        l_fs [label="filesystem" shape=folder fillcolor="#2a2a3e" color="#585b70"]
+    }
+}