---
id: meta-architecture-decisions
title: Architecture Decisions
slug: /meta/architecture-decisions
---

A lightweight record of the decisions that shape BlackRoad OS. Expand with ADRs as the stack grows.

1. **PS-SHA∞ as the global identity anchor** — all humans, agents, and assets must carry PS-SHA∞ anchors to make auditability universal.
2. **Operator runs the work** — jobs and agents execute only inside `blackroad-os-operator`; other repos should not duplicate execution loops.
3. **API is the single HTTP surface** — `blackroad-os-api` is the contract for external consumers; Operator’s `/internal/*` routes are for orchestration tooling only.
4. **Prism is for operators; Web is for public storytelling** — keep the ops UI and public shell distinct so narratives and sensitive data do not mix.
5. **RoadChain is the audit substrate** — every DomainEvent rolls into journal entries and blocks; corrections are additive, not mutable.
6. **Docs stay canonical** — `blackroad-os-docs` is the source of truth for architecture language and cross-repo alignment and participates in the "BlackRoad OS - Master Orchestration" project.

When proposing changes, add context here or link to a dedicated ADR so future contributors and agents can understand why a decision exists.