commit fc864b7e489439bd6b4afc8b047b1f87b557631d Author: jlcm Date: Sat May 9 05:33:06 2026 +0000 Add READ diff --git a/READ b/READ new file mode 100644 index 0000000..a9013f3 --- /dev/null +++ b/READ @@ -0,0 +1,130 @@ +# WDM + +**Watch · Detect · Manage** + +Blocao Labs platform repository — distributed edge AI for video and audio forensics with full data sovereignty. + +This repository is the single source of truth for the design, architecture, mockups, sprint backlog, and decisions taken during the initial design phase of the Blocao platform. It is documentation-first: code lives in sibling repositories that this one references. + +--- + +## What this is + +Blocao is a **vertically integrated edge AI platform** for sites that need: + +- IP camera forensics with cross-AI fusion (video + audio + access events). +- Audio transcription with speaker diarization, topic search, and forensic playback. +- Full data sovereignty: nothing leaves the site unless explicitly bridged. +- Open-source stack on commodity hardware (OpenWrt + RK3588). +- GitOps-managed configuration auditable by anyone with read access to the repo. + +It is **not** a re-skin of an existing VMS, **not** a SaaS, and **not** a hyperscaler-cloud product. The competitive positioning, technical contracts, and target markets are documented in `docs/`. + +--- + +## Repository layout + +``` +wdm/ +├── README.md ← you are here +├── WIKI.md ← human-friendly entry point with deeper navigation +├── docs/ ← architecture, products, design language, deployments +├── backlog/ ← user stories, sprint plan, cross-product reuse +├── mockups/ ← clickable HTML prototypes (LCARS-style) +└── decisions/ ← lightweight ADRs for major design choices +``` + +If you want the **executive briefing**, read `WIKI.md`. If you want to **start a sprint**, jump to `backlog/sprint-plan.md`. If you want to **see the product**, open the HTML files in `mockups/`. + +--- + +## Quick orientation by role + +**You are an investor or non-technical stakeholder** → start with `docs/00-vision.md`, then open `mockups/index.html` in a browser to feel the product. + +**You are a developer joining the project** → read `WIKI.md` end to end, then `docs/01-architecture/overview.md`. Pick a sprint from `backlog/sprint-plan.md` and find the corresponding stories. + +**You are an ops / SRE** → `docs/01-architecture/tiers.md` and `docs/04-deployments/single-site.md` describe what you'll be running. The runbooks in `docs/07-runbooks/` are still placeholders. + +**You are a designer** → `docs/03-design/` has the design tokens, the LCARS language adaptation, and the brand guidelines. The `mockups/` folder contains the live prototypes. + +**You are a salesperson or partner** → `docs/05-comparatives/` has structured comparisons against Verkada, Milestone, Frigate-DIY and Hikvision. `docs/04-deployments/argentina-targets.md` has the geographic-vertical map for the LATAM market. + +--- + +## Vocabulary + +A few terms that recur throughout the documentation: + +| Term | Meaning | +|---|---| +| **Site** | One physical location with a Blocao deployment. Identified as `BL-`. | +| **Router** | OpenWrt device serving as network gateway, broker, and console host. | +| **Cell** | RK3588-class edge AI device running Frigate + supporting services. Tier-1 compute. | +| **Core** | Tier-2 coordinator (e.g. Jetson Orin) federating multiple Cells. Optional. | +| **Hub** | Remote multi-site control plane operated by the customer or by Blocao Labs. | +| **Operator** | End user of the console (security investigator, ops). | +| **Installer** | Field technician deploying a site. | +| **Tier topology** | Notation `R+1`, `R+3+C` etc. indicating router plus N Cells plus optional Core. | +| **Sovereignty layer** | The set of policies in MQTT, GitOps and storage that control what data leaves the site. | + +--- + +## Mockups + +The `mockups/` folder contains self-contained HTML files that work offline. Open them in any modern browser: + +- **`index.html`** — the unified operator console. Aterriza en SYNOPSIS (SCADA-style live diagram). Rail izquierdo navega entre vistas Engineering, Operator, System. +- **`transcript-forensics.html`** — audio transcription forensics panel: query, waveform, speaker diarization, topic search, audio player. +- **`forensics-only.html`** — earlier standalone version of the video forensics panel. +- **`gitops-only.html`** — earlier standalone version of the GitOps panel. +- **`frigate-config.html`** — Frigate integration mockup with cameras list and config. +- **`palette-comparison.html`** — classic LCARS vs complementary palette toggle. +- **`router-ui-original.html`** — the very first sketch of the router console. Kept for historical reference. + +The visual language is **LCARS-inspired with a complementary palette** (cyan-dominant instead of orange). The decision and the rationale are in `decisions/0001-paleta-complementaria.md`. + +--- + +## Sprint readiness + +The backlog in `backlog/` is structured into **8 epics** mapping to ~19 weeks of work to first demoable product. The plan, dependencies, and risk register are documented. Stories are tagged `BL-XX.Y` for Blocao and `WDM-T-XX.Y` for transcript-specific items, with a third file (`shared-stories.md`) listing items that cut across both products. + +Sprint 0 (foundation) should be closed before any UI work starts — it covers the monorepo, CI, OpenWrt Image Builder and Balena fleet provisioning. From sprint 1 onward, each sprint produces a demoable increment. + +**MVP demo readiness**: end of sprint 4. The full hub + multi-site experience: end of sprint 6. Legal-grade evidence chain: end of sprint 7. + +--- + +## Decisions + +Major design decisions are recorded as lightweight ADRs in `decisions/`. They are numbered, dated, and never edited after acceptance — superseding decisions get a new number. Current set: + +1. Complementary palette over classic LCARS. +2. Tier hierarchy (Router / Cell / Core / Hub). +3. MQTT as the spine of the system. +4. GitOps as source of truth. +5. Sovereignty over hyperscaler convenience. +6. Router serves the console shell, Cell provides APIs. +7. Evidence chain is a separate workstream, not blocking demo. +8. Default 30-day retention for Argentina deployments. +9. No redundant titles in the UI (rail + topbar + ctx-strip pattern). +10. SYNOPSIS as the landing view. + +--- + +## Status + +This repository is in **design phase**. No production code is referenced yet. When the first companion repos are created (`apps/console`, `apps/router-luci-app`, `apps/cell-services`, `apps/hub`), they will be linked from `WIKI.md`. + +Issues raised here track design decisions and backlog grooming. Implementation issues should be opened in their respective code repositories with a back-reference to the relevant `BL-XX.Y` story. + +--- + +## License & confidentiality + +Internal Blocao Labs material. Not for distribution outside the team. Licensing for the open-source components will be decided per-repository when code starts shipping. + +--- + +*Last reviewed: see commit history. Maintained by Blocao Labs.* \ No newline at end of file