From 2350fd7b30096e7102e12fec39679e8deba3b1b3 Mon Sep 17 00:00:00 2001 From: Eratostenes de Gitjabia Date: Sat, 9 May 2026 12:28:00 +0000 Subject: [PATCH] docs: add WIKI.md as human-friendly entry point --- WIKI.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 WIKI.md diff --git a/WIKI.md b/WIKI.md new file mode 100644 index 0000000..6657217 --- /dev/null +++ b/WIKI.md @@ -0,0 +1,116 @@ +# Blocao · Wiki + +This is the human-friendly entry point to the WDM repository. Start here if you want context before diving into specific files. + +--- + +## Where everything lives + +| You want... | Go to | +|---|---| +| Executive briefing | [`docs/00-vision.md`](docs/00-vision.md) | +| Architecture overview | [`docs/01-architecture/overview.md`](docs/01-architecture/overview.md) | +| Tier hierarchy explained | [`docs/01-architecture/tiers.md`](docs/01-architecture/tiers.md) | +| MQTT contracts | [`docs/01-architecture/mqtt-contract.md`](docs/01-architecture/mqtt-contract.md) | +| Sovereignty model | [`docs/01-architecture/data-sovereignty.md`](docs/01-architecture/data-sovereignty.md) | +| Storage and retention math | [`docs/01-architecture/storage-retention.md`](docs/01-architecture/storage-retention.md) | +| Network topology and VLANs | [`docs/01-architecture/network-topology.md`](docs/01-architecture/network-topology.md) | +| Blocao product | [`docs/02-products/blocao-overview.md`](docs/02-products/blocao-overview.md) | +| Transcript product | [`docs/02-products/transcript-overview.md`](docs/02-products/transcript-overview.md) | +| What both products share | [`docs/02-products/shared-stack.md`](docs/02-products/shared-stack.md) | +| Design tokens | [`docs/03-design/design-tokens.md`](docs/03-design/design-tokens.md) | +| UI patterns | [`docs/03-design/ui-patterns.md`](docs/03-design/ui-patterns.md) | +| LCARS adaptation rationale | [`docs/03-design/lcars-language.md`](docs/03-design/lcars-language.md) | +| Brand guidelines | [`docs/03-design/brand-blocao.md`](docs/03-design/brand-blocao.md) | +| Single-site deployment | [`docs/04-deployments/single-site.md`](docs/04-deployments/single-site.md) | +| Multi-site fleet | [`docs/04-deployments/multi-site-fleet.md`](docs/04-deployments/multi-site-fleet.md) | +| HaLow extended-range variant | [`docs/04-deployments/halow-extended-range.md`](docs/04-deployments/halow-extended-range.md) | +| Argentina target verticals | [`docs/04-deployments/argentina-targets.md`](docs/04-deployments/argentina-targets.md) | +| vs Verkada / Rhombus | [`docs/05-comparatives/vs-verkada.md`](docs/05-comparatives/vs-verkada.md) | +| vs Milestone | [`docs/05-comparatives/vs-milestone.md`](docs/05-comparatives/vs-milestone.md) | +| vs Frigate-DIY | [`docs/05-comparatives/vs-frigate-diy.md`](docs/05-comparatives/vs-frigate-diy.md) | +| vs Hikvision / Dahua | [`docs/05-comparatives/vs-hikvision.md`](docs/05-comparatives/vs-hikvision.md) | +| Argentine retention law | [`docs/06-legal/retention-argentina.md`](docs/06-legal/retention-argentina.md) | +| EU retention law | [`docs/06-legal/retention-eu.md`](docs/06-legal/retention-eu.md) | +| Evidence chain roadmap | [`docs/06-legal/evidence-chain-roadmap.md`](docs/06-legal/evidence-chain-roadmap.md) | +| Sprint backlog · Blocao | [`backlog/blocao-sprint-backlog.md`](backlog/blocao-sprint-backlog.md) | +| Sprint backlog · Transcript | [`backlog/transcript-sprint-backlog.md`](backlog/transcript-sprint-backlog.md) | +| Cross-product reuse | [`backlog/shared-stories.md`](backlog/shared-stories.md) | +| Sprint plan & calendar | [`backlog/sprint-plan.md`](backlog/sprint-plan.md) | +| Mockup index | [`mockups/README.md`](mockups/README.md) | +| Decision history | [`decisions/README.md`](decisions/README.md) | + +--- + +## Status snapshot + +**Phase**: design (no production code yet). + +**Mockups available**: +- Operator console (SYNOPSIS, CAMS, FRIGATE, GITOPS, MQTT, HEALTH, FORENSICS, setup wizard, camera onboarding). +- Audio transcript forensics panel. + +**Decisions taken**: 10 ADRs (see `decisions/`). + +**Sprint plan**: 8 epics, ~19 weeks to first MVP demo. + +**Next milestone**: close Sprint 0 (foundation) before any UI work begins. + +--- + +## How to contribute + +1. **Design discussion** → open an issue tagged `discussion` and link to relevant decision/doc. +2. **New ADR** → propose in an issue, agree, then PR with the ADR file numbered next in sequence. +3. **Backlog grooming** → comment on individual story issues. Story IDs are `BL-XX.Y` for Blocao and `WDM-T-XX.Y` for transcript-specific. +4. **Mockup iteration** → branch from `main`, modify the relevant `mockups/*.html`, PR with screenshots. +5. **Documentation** → keep prose tight, prefer tables over bullet lists when comparing things, link liberally to other docs. + +Avoid: + +- Editing accepted ADRs. Supersede with a new number instead. +- Adding new mockup files for minor variations of existing ones — branch and edit. +- Putting code in this repo. Code lives in companion repositories (when those exist). + +--- + +## Glossary (extended) + +For the short version see the README. Extended terms: + +| Term | Meaning | +|---|---| +| **Bridge** | The mosquitto-to-mosquitto MQTT connection between site router and hub. Selectively configured to enforce sovereignty. | +| **Drift** | When the live config on disk diverges from what the GitOps repo says it should be. | +| **Edge AI** | AI inference running on-site (Cell or Core), not in cloud. | +| **Enricher** | Service that consumes detection events and adds embeddings, hashes, re-ID vectors. | +| **Evidence pack** | An exportable bundle of clips + manifests + custody log for a case. | +| **Fleet token** | Single-use token issued by the hub during enrollment of a new site. | +| **Frigate** | Open-source NVR + edge AI engine. The first edge AI integrated. | +| **HAI** | Internal abbreviation for "Hardware AI". Now mostly replaced by "edge AI" in customer-facing copy. | +| **Quarantine VLAN** | The cameras VLAN (default VLAN-10) with zero internet egress. | +| **Reconcile** | The router's process of fetching latest GitOps config and applying differences. | +| **Selftest** | The 5-minute periodic health check ran by `healthd`. | +| **SP-A / SP-B / SP-C** | Speaker labels used in transcript forensics when speakers haven't been identified by voiceprint. | +| **Voiceprint** | Speaker embedding stored in the speaker library, used to identify speakers in new sessions. | + +--- + +## Why "WDM" + +**WDM = Watch · Detect · Manage**. The three operations the platform performs at every site, in that order: + +1. **Watch** — capture video and audio streams. +2. **Detect** — run edge AI to extract events, embeddings, transcripts. +3. **Manage** — orchestrate the fleet, enforce sovereignty policies, surface insights to operators. + +The product name remains **Blocao**. WDM is the internal name of the platform layer and this design repository. + +--- + +## Maintainers + +- **Design + product**: Blocao Labs core team. +- **This repo**: documentation-first. Code repos will be linked when they exist. + +For questions before contributing: open an issue, no need to ask permission.