ADR-0000: Documentation Architecture -- Two-Tier Model, 3-Class Taxonomy, 11-Prefix Scheme¶
Status¶
Accepted -- 2026-05-02
Author: Ben Peries (orchestrator session 05-01-26-A)
Context¶
The Archon Platform accumulated 56 ADRs in a flat docs/adr/ directory with sequential
numbering (0001--0046) plus 10 OT-prefixed ADRs. This flat structure created several
compounding problems:
- Portfolio audience confusion. Security-sensitive decisions (threat posture, IAM, supply chain) lived alongside public-navigable IT operational decisions. No structural distinction existed between what was internal-only and what was safe to publish.
- No thematic navigation. Finding all observability decisions, or all OT decisions, required manual scanning. No prefix or folder scoping existed.
- Decision-vs-doc conflation. Operational runbooks, tool version pins, and config-change records were being recorded as ADRs. This inflated the ADR count and diluted the audit value of the record.
- No public/internal distinction. The sanitization pipeline redacted content at the string level but had no structural mechanism to block entire ADR classes from public view.
- Numbering exhaustion risk. Sequential flat numbering provides no thematic grouping and makes consolidation or supersession harder to reason about.
The documentation base needed a structural reform that would: 1. Separate decisions by security classification zone (IT vs OT, per IEC 62443) 2. Separate decisions by domain theme (governance, IAM, observability, etc.) 3. Establish a tiered public/internal model for the built site 4. Provide a canonical policy for when to create, amend, or retire an ADR
Decision¶
Two-Tier Documentation Model¶
All documentation in archon-docs is organized into three tiers:
Tier 1 -- Architectural Decisions (ADRs)
- Path: docs/adr/{class}/{prefix}/
- Contents: numbered, immutable architectural decision records
- Audience: internal (all ADR content treated as internal by default)
- Exception: RISK-class ADRs are Tier 1 only and never published
Tier 2 -- Public Narrative (Architecture)
- Path: docs/architecture/{class}/
- Contents: sanitized, general-concept pages citing ADRs; no internal identifiers
- Audience: public portfolio (deployed to Cloudflare Pages via sanitize.py)
- DLP requirement: all Tier 2 pages must pass verify-sanitization.py
Tier 3 -- Internal Operational
- Paths: docs/internal/, docs/runbooks/, docs/platform/, docs/reference/,
docs/conventions/, docs/golden-paths/, docs/best-practices/
- Contents: runbooks, onboarding guides, platform state, tool selection pages
- Audience: internal operators; excluded from public build by sanitize.py
3-Class Taxonomy¶
All ADRs belong to exactly one of three classes:
| Class | Path | IEC 62443 Zone | Scope |
|---|---|---|---|
security/ |
docs/adr/security/ |
Cross-cutting | Applies to all zones; governs policy, IAM, APPSEC, SECOPS |
it/ |
docs/adr/it/ |
IT zone | Information technology infrastructure and developer tooling |
ot/ |
docs/adr/ot/ |
OT zone | Operational technology, embedded systems, sensor networks |
11-Prefix Scheme¶
Each prefix maps to a domain within a class. Each prefix restarts numbering at 0001 and is chronological within the prefix.
Security Class¶
| Prefix | Domain | Tier 2 publishable? |
|---|---|---|
GOV |
Governance and process policy | Yes -- general principles only |
RISK |
Risk register and threat posture | No -- Tier 1 internal only |
IAM |
Identity and access management | Yes -- sanitized (no account names, UIDs, key material) |
APPSEC |
Application and supply-chain security | Yes -- sanitized (no CVE remediation specifics) |
SECOPS |
Security operations and purple team | Yes -- sanitized (no TTPs, no tool configs) |
IT Class¶
| Prefix | Domain | Tier 2 publishable? |
|---|---|---|
PLAT |
Platform infrastructure (k3s, OPNsense, Docker) | Yes -- sanitized |
NET |
Network architecture (DNS, VPN, firewall, VLAN) | Yes -- sanitized |
OBS |
Observability stack (metrics, logs, dashboards) | Yes -- sanitized |
DEV |
Developer environment and CI/CD tooling | Yes -- sanitized |
LLMOPS |
LLM operations and AI agent plane | Yes -- sanitized |
OT Class¶
| Prefix | Domain | Tier 2 publishable? |
|---|---|---|
OT |
All OT decisions (hardware, MQTT, historian, alarms) | Yes -- process-level only; no sensor node IDs, MQTT topic paths, or historian schema details |
Numbering Policy¶
- Format:
{PREFIX}-{NNNN}where NNNN is zero-padded to 4 digits - Numbering restarts at 0001 per prefix
- Chronological within prefix; no gaps permitted
- Legacy flat ADRs (0001--0046, OT-0001--OT-0010) are renumbered per ADR-0047
- ADR-0000 (this document) and ADR-0047 (migration bridge) remain at the root
docs/adr/as anchors and are not subject to prefix numbering
Classification Rules by Class¶
security/ class:
- GOV: Tier 2 publishable -- general governance principles; no sprint names, WI IDs,
or session identifiers in published content
- RISK: Tier 1 only; never published; excluded from sanitize.py output
- IAM: Tier 2 sanitized -- service account names, UID assignments, key material,
and Infisical paths must be redacted
- APPSEC: Tier 2 sanitized -- scanner names, scoring, and approved tool list are
publishable; CVE IDs and remediation specifics are not
- SECOPS: Tier 2 sanitized -- methodology and tooling class publishable;
TTP details, purple team findings, and engagement specifics are not
it/ class:
- PLAT: Tier 2 sanitized -- architectural patterns and component selection publishable;
hostnames, IPs, kubeconfig details, and version pins are not
- NET: Tier 2 sanitized -- topology patterns and zone model publishable;
internal subnets, firewall rules, and port maps are not
- OBS: Tier 2 sanitized -- stack architecture and data plane design publishable;
internal dashboards, Grafana UIDs, and retention specifics are not
- DEV: Tier 2 sanitized -- toolchain selection and rationale publishable;
workstation specs, internal paths, and credential patterns are not
- LLMOPS: Tier 2 sanitized -- model selection rationale and agent architecture
publishable; API endpoints, model version pins, and cost data are not
ot/ class:
- OT: Tier 2 sanitized -- process-level architectural decisions publishable;
sensor node IDs, OT zone identifiers, MQTT topic paths, InfluxDB org name,
historian schema, alarm implementation IDs, and Grafana OT dashboard UIDs are not
DLP Regex Requirements¶
The following patterns must be present in sanitize.py and verify-sanitization.py
to gate public publication:
| Category | Pattern | Action |
|---|---|---|
| Service account names | ansible-svc-account, ansible-ot-svc-account |
Replace with canonical alias |
| OT sensor node IDs | cae[0-9]+ot[0-9]+(snr\|cam\|gwy\|ctr\|dsp\|pwr\|hvc\|mtr\|aud\|net\|sec\|env)[0-9]{2} |
Replace with sanitized alias |
| OT zone identifiers | ot[1-4] in location/MQTT context |
Replace with ot-zone |
| MQTT topic prefixes | caneast/ot[1-4]/ |
Replace with caneast/ot-zone/ |
| InfluxDB org name | REDACTED |
Replace with REDACTED |
| ISA alarm IDs | ALM-00[1-9][0-9]* |
Replace with ALM-REDACTED |
| Grafana resource UIDs | 12+ char alphanumeric UID strings | Replace with REDACTED |
| UID assignments | UID (1100\|1500) in service account context |
Replace with UID REDACTED |
| IT hostname patterns | cae[0-9]+node[0-9]+, cae[0-9]+mqtt[0-9]+ |
Replace via NODE_PATTERNS |
| Internal subnets | 192\.168\.2\.[0-9]+ |
Replace via RFC1918_PATTERN |
These patterns supplement the existing patterns already in the sanitization pipeline.
Phase B of ADR-0047 migration adds them to sanitize.py and verify-sanitization.py.
ADR Creation Policy¶
This policy is in force as of 2026-05-02. All agents and operators creating ADRs in
archon-docs or archon-platform must follow this policy. CLAUDE.md files in all
repos point here as the canonical source.
Step 1 -- Identify class and prefix¶
Before writing anything:
1. Identify which class applies: security/, it/, or ot/
2. Identify which prefix applies from the 11-prefix scheme above
3. Read all existing ADRs in that prefix directory
Step 2 -- Apply the AMEND-OR-CREATE-OR-WIKI decision tree¶
AMEND (default -- preferred)
Use AMEND when the decision is a refinement, scope expansion, or implementation update of an existing ADR in the same prefix with fewer than 5 dated addendums and Accepted status.
How: append ## Addendum -- YYYY-MM-DD to the existing ADR. Do not edit the original
Decision section. Addendums are dated and attributed.
CREATE
Use CREATE only when: - The decision establishes a new architectural pattern not covered by any existing ADR in the prefix, OR - The decision requires substantial alternatives-considered reasoning that does not fit an addendum, OR - No existing ADR in the prefix covers the domain
Requirement: before authoring a new ADR, document the following in the ADR's Context section: "I considered amending {ADR-XXXX}. Amendment not appropriate because: {reason}."
WIKI INSTEAD
Use a wiki page (Tier 2 or Tier 3) instead of an ADR when the content is: - Tool selection or version pin (not an architectural pattern) - Operational runbook or how-to guide - Current-state architecture documentation - Onboarding or orientation material
Target paths:
- docs/architecture/ (Tier 2, public-sanitized)
- docs/internal/, docs/runbooks/, docs/platform/, docs/reference/ (Tier 3, internal)
Forbidden ADR patterns¶
- Creating an ADR for every Sprint deliverable or task completion
- Creating an ADR for tool version pins or config changes that follow an existing pattern
- Creating an ADR before reading the prefix directory
- Creating an ADR when the content belongs in a runbook or wiki page
Consequences¶
Positive: - Portfolio coherence: security class is structurally separated from IT and OT, enabling class-level publication controls - Audit discoverability: prefix grouping makes it possible to find all IAM decisions, all OT decisions, or all governance decisions without scanning all 56+ ADRs - DLP enforcement: Tier 1 / Tier 2 / Tier 3 structural separation reduces dependence on content-level sanitization alone - ADR creation discipline: the AMEND-OR-CREATE-OR-WIKI policy prevents ADR inflation and keeps the decision record meaningful
Negative: - Migration cost: 56 existing ADRs must be moved, renumbered, or consolidated per ADR-0047 - Cross-reference churn: all existing "see ADR-XXXX" references must be updated to new paths - Nav restructure: mkdocs.yml flat ADR list must be replaced with hierarchical nav
Mitigations: - Migration is phased per ADR-0047 (Phases A--H); no single mega-PR - Legacy ADR files at old paths retained with deprecation banners during transition - ADR-0047 serves as the canonical old-to-new mapping reference
References¶
- ADR-0047: Documentation Architecture Migration Bridge (old-to-new mapping)
- ADR-0005 (now IAM-0002): IT/OT zone separation -- motivates the 3-class taxonomy
- ADR-0017 (now APPSEC-0002): Public docs pipeline -- DLP rules this ADR expands
- CLAUDE.md (all repos): ADR Creation Policy section points here as canonical source
- IEC 62443: IT/OT zone separation standard (motivation for security/ vs it/ vs ot/ split)