From bc1badc89f6c78497d411538cf3f6a636b9457e4 Mon Sep 17 00:00:00 2001
From: Eratostenes de Gitjabia <eratostenes@blocaolabs.com>
Date: Sat, 9 May 2026 12:31:56 +0000
Subject: [PATCH] docs(architecture): storage and retention math

---
 docs/01-architecture/storage-retention.md | 86 +++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 docs/01-architecture/storage-retention.md

diff --git a/docs/01-architecture/storage-retention.md b/docs/01-architecture/storage-retention.md
new file mode 100644
index 0000000..e66816e
--- /dev/null
+++ b/docs/01-architecture/storage-retention.md
@@ -0,0 +1,86 @@
+# Storage and retention
+
+Capacity planning for Blocao Cells.
+
+## Bitrate budget
+
+Default policy: dual-stream recording per camera.
+
+| Stream | Resolution | Codec | Bitrate | Use |
+|---|---|---|---|---|
+| Main | 1080p @ 15fps | H.265 | ~2.0-2.5 Mbps | Event-triggered clips |
+| Sub | 480p @ 5fps | H.265 | ~280-400 Kbps | Continuous recording |
+
+**Per camera, per day**:
+
+- Main (event-triggered, ~10% activity): ~2.0 Mbps × 86400s × 10% = ~2.0 GB
+- Sub (continuous): ~0.3 Mbps × 86400s = ~3.2 GB
+- Subtotal: ~5.2 GB/cam/day
+- With 90% efficiency for fragmentation/index: ~5.8 GB/cam/day
+
+## Retention math
+
+| Cameras | Days | Total | Recommended disk |
+|---|---|---|---|
+| 4 | 30 | ~700 GB | NVMe 500GB hot + HDD 2TB cold |
+| 8 | 30 | ~1.4 TB | NVMe 500GB hot + HDD 4TB cold |
+| 8 | 60 | ~2.8 TB | NVMe 1TB hot + HDD 4TB cold |
+| 8 | 90 | ~4.2 TB | NVMe 1TB hot + HDD 6TB cold |
+| 16 | 30 | ~2.8 TB | NVMe 1TB hot + HDD 6TB cold |
+| 16 | 90 | ~8.4 TB | NVMe 2TB hot + HDD 12TB cold |
+
+Numbers include 10% buffer for fragmentation and indexing.
+
+## Hot/cold tiering
+
+Frigate writes to the hot tier (NVMe). A nightly job moves files older than 7 days to the cold tier (HDD). The hot tier is the working set: recent events, today's queries.
+
+The cold tier holds the rest of retention. HDDs preferred for cold:
+
+- **WD Purple** (surveillance-rated): 4TB, 6TB, 8TB sweet spot.
+- **Seagate SkyHawk** (also surveillance-rated): equivalent.
+- Avoid consumer drives (e.g. WD Blue): they're not rated for 24/7 write workloads.
+
+NVMe options:
+
+- **Samsung 990 Pro** or **Crucial T700**: high endurance, MLC.
+- 500GB minimum; 1TB recommended for sites with >8 cameras.
+
+## Buffer policy
+
+Soft and hard limits on disk usage:
+
+| % used | Status | Action |
+|---|---|---|
+| < 75% | Healthy | Normal operation |
+| 75-85% | Soft limit | Alert in HEALTH panel; oldest events flagged for removal |
+| 85-95% | Hard limit | Aggressive pruning of low-importance events; warning in SYNOPSIS |
+| > 95% | Critical | Stop writing new clips, only keep in-memory; alert at hub level |
+
+The **evidence locker** is a separate partition with its own quota. Pinned-to-case clips move there and are not subject to retention rotation. Default evidence locker: 100GB on NVMe.
+
+## Encryption
+
+LUKS on both NVMe and HDD partitions.
+
+Key management:
+
+- **Default**: key file on the Cell, protected by hardware secure element when available (RK3588 has a Cryptographic Engine — not currently used; planned for hardening).
+- **Customer BYOK**: customer-supplied key, sealed by Tang+Clevis or HashiCorp Vault.
+
+The encryption is **at rest only**. Frigate works on plaintext within RAM and over LAN inside VLAN-20.
+
+## Backup considerations
+
+Per-site backup is **not** the default — most customers don't want extra disks at every site. Options:
+
+1. **No backup**: accept the 30-day window as the SLA. If the Cell dies, data lost.
+2. **Hub mirror**: events and embeddings replicate to hub; raw video doesn't. Customer can reconstruct history via embeddings + bring back from a pinned-case archive.
+3. **Customer-side rsync**: nightly cron pushes evidence locker only to customer's NAS.
+
+For Argentina banking deployments (BCRA 90-day retention), option 2 is the typical answer. The hub holds enough metadata to prove "events occurred at time X" even if the raw clip is lost.
+
+## See also
+
+- [`data-sovereignty.md`](data-sovereignty.md) — encryption and what leaves the site.
+- [`../06-legal/retention-argentina.md`](../06-legal/retention-argentina.md) — regulatory baselines.