Architecture Repository

Document Status

Approved

Purpose

This repository is the authoritative architecture source of truth for the system.

Important

Getting Started: If you are new to this repository (human or AI), please read the How to Start onboarding guide first to understand the workspace setup, decision-making framework, and operational rules.

Owner

TBD

Last Updated

2026-06-11

Audience

• Product
• Architecture
• Engineering
• Security
• Operations
• AI-assisted development tools

Guiding Principles

• Documentation as Code: Architecture is versioned, reviewed, and maintained alongside code.
• Architecture Before Implementation: Design decisions and models are defined before construction.
• Decisions Over Opinions: Architectural choices are documented through formal Architecture Decision Records (ADRs).
• Explicit Boundaries: Clear boundaries are established between systems, domains, and responsibilities.
• Single Authoritative Source: Every concept has one primary source of truth, referencing rather than duplicating.
• Glossary First Vocabulary: Domain and technical terms must be defined in the glossary before broad usage.
• Archive Rather Than Delete: Superseded documents are moved to the archive directory rather than deleted to retain history.

Repository Navigation

• how-to-start.md: Onboarding guide and operational workflow (Read this next).
• onboarding-dev.md: Developer-specific onboarding with local verification commands.
• glossary.md: Authoritative domain vocabulary and technical terms.
• architecture/: System contexts, views, and specific sub-system templates.
• decisions/: Architecture Decision Records (ADRs).
• standards/: Engineering, coding, testing, and quality attribute standards.
  • quality-attributes.md: Non-functional requirement targets.
  • architectural-decision-matrix.md: Topology selection framework.
• governance/: Risk logs, assumption trackers, and open questions.
  • risks.md: Risk register.
  • assumptions.md: Documented assumptions.
  • migration_log.md: Change and migration history.
  • red-team-audit-report.md: Documentation linter audit findings.
• archive/: Retrospective, superseded, or legacy architectural artifacts.

Operational Guide

1. File Metadata Header Rule

Every new markdown file created in this repository must begin with the following metadata header block:

# [Document Title]

## Document Status
Draft

## Purpose
<!-- AI_HINT: PENDING_DISCOVERY - DO NOT AUTOFILL -->
TBD

## Owner
<!-- AI_HINT: PENDING_DISCOVERY - DO NOT AUTOFILL -->
TBD

## Last Updated
YYYY-MM-DD

2. Incomplete Sections

Do not use naked TBD or custom placeholders. Every incomplete section must use:

<!-- AI_HINT: PENDING_DISCOVERY - DO NOT AUTOFILL -->
TBD

3. Structural Link Rules

All cross-document references must use relative paths (e.g. [Standards](./standards/technical-standards.md)), never root-absolute paths or Windows backslash paths.

4. Running the Local Linter

To verify structural rules locally before pushing changes to GitHub:

python3 verify_docs.py

5. Marking Architectural Gaps

When a section or decision is known to be incomplete but the answer is not yet available, use an ARCH-GAP inline comment tag rather than leaving a bare TBD. This allows the audit scripts to inventory all open gaps across the repo.

<!-- ARCH-GAP: [Short description of what is unknown or unresolved]. [Owner: Team/Person]. -->

• Owner: is required — the audit script will flag gaps without an owner.
• ARCH-GAP tags appear in the verify_coverage.py gap inventory report.
• Once resolved, remove the comment and document the decision in an ADR if appropriate.

7. AI System Instructions (Behavioral Rules)

If you are an AI assistant or agent reading this repository:

• Ignore the /archive Directory: Do not read, search, or index documents under archive/ unless the user explicitly instructs you to reference deprecated or legacy documents.
• Source of Truth: Treat only the active directories (architecture/, standards/, decisions/, governance/, and glossary.md) as the current authoritative state.
• No Invention: Do not extrapolate or invent system actors, requirements, integration systems, or technologies that are not explicitly documented.