From b425bf443a43beaec0da38b9dc74153bc4a10fe0 Mon Sep 17 00:00:00 2001
From: Eratostenes de Gitjabia <eratostenes@blocaolabs.com>
Date: Sat, 9 May 2026 12:34:02 +0000
Subject: [PATCH] docs(products): shared stack analysis

---
 docs/02-products/shared-stack.md | 67 ++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/02-products/shared-stack.md

diff --git a/docs/02-products/shared-stack.md b/docs/02-products/shared-stack.md
new file mode 100644
index 0000000..a1fd711
--- /dev/null
+++ b/docs/02-products/shared-stack.md
@@ -0,0 +1,67 @@
+# Shared stack · what Blocao and Transcript have in common
+
+The two products share most of their stack. This file maps the shared vs distinct parts to inform engineering decisions and avoid duplication.
+
+## Shared 100%
+
+| Layer | Component |
+|---|---|
+| Hardware (router) | OpenWrt router |
+| Hardware (compute) | RK3588 Cell |
+| OS (Cell) | Balena |
+| Network model | VLANs, firewall, DNS sinkhole |
+| Broker | Mosquitto + bridge |
+| Time sync | chrony with NTS |
+| VPN | Tailscale |
+| Configuration | GitOps |
+| Hub | Same Hetzner bare-metal infrastructure |
+| Auth | Keycloak on hub |
+| Sovereignty model | Same VLAN/bridge/storage tiering |
+
+## Shared with adaptation
+
+| Layer | Component | What changes |
+|---|---|---|
+| **Console framework** | SPA shell + design tokens + LCARS chrome | Same shell; product-specific panels added |
+| **Chat query UI** | Pattern with ghost-text autocomplete + agent pipeline | Vocabulary differs; layout identical |
+| **Timeline** | Time-axis with markers + playhead | Marker semantics differ (event vs speech segment) |
+| **Player** | Scrubber + correlated metadata + caption | Video player vs audio player; same shell |
+| **Case management** | Pin-to-case, evidence pack export | Same model; different evidence types |
+| **Embeddings store** | Qdrant | Same software; separate collections (visual vs voiceprint) |
+| **Health** | Selftest engine | Mostly same checks; product-specific tests for STT readiness |
+| **Evidence chain** | Hash + manifest + signature | Same flow; manifest schema differs slightly |
+
+## Product-specific (Blocao)
+
+| Component | Description |
+|---|---|
+| Frigate container | RTSP ingest + detection |
+| Frigate enricher | CLIP embeddings, re-ID, hashing |
+| Camera onboarding flow | Discovery, ONVIF, RTSP probe |
+| Video clip storage tier | Hot NVMe + cold HDD |
+| LPR / vehicle / animal classifiers | Specialized detection types |
+
+## Product-specific (Transcript)
+
+| Component | Description |
+|---|---|
+| Whisper container | STT engine |
+| pyannote container | Diarization |
+| Speaker library | Voiceprint storage and matching |
+| Audio ingest interface | USB mic, line-in, SIP, file upload |
+| Topic detection (NER + clustering) | Identifies subjects discussed |
+| Insistence analyzer | Per-speaker intervention pattern analysis |
+
+## Engineering implications
+
+1. **The console framework is product-agnostic**. It should be designed as a shell that loads product-specific panels.
+2. **The Cell stack is product-extensible**. The same Balena fleet can run Blocao containers, transcript containers, or both.
+3. **The hub schema must accommodate both**. Site → Cell → Service → Capability hierarchy where Capability is `frigate | enricher | whisper | pyannote | re-id | ...`.
+4. **GitOps repos are unified**. Both products share `fleet-config` for org-wide settings and `site-config` for per-site config.
+5. **The MQTT contract has namespace separation**. Video events are `hai/<cam_id>/...`; audio events would be `aud/<source_id>/...`. Both follow the same patterns; bridge policy generalizes.
+
+## Backlog implications
+
+Stories that touch shared components are tracked in `backlog/shared-stories.md` to avoid duplicate work. The `BL-XX.Y` and `WDM-T-XX.Y` story IDs reference shared stories explicitly when relevant.
+
+Sprint planning should sequence shared infrastructure (Sprint 0 + selected items from Epics 0-2-5-6) **before** product-specific work, so both products benefit.