Substratum.cloud

Appearance

Architecture Directory - AI Agent Instructions ​

Last Updated: 2026-06-12 (ADR 43 centralized log observability)

This directory contains the codified architectural decisions for Substratum v1.0. These documents are the source of truth for system boundaries, design patterns, and implementation strategies.

📝 Documentation Rules for Architecture ​

  • Conciseness: Keep documents short, focused, and easily digestible. Avoid long, rambling paragraphs.
  • ADR structure: New and substantially revised ADRs use template.md: Terms (this ADR) (including R / NR / C / CC legend and ADR-specific acronyms), Requirements, Constraints, Cross-cutting challenges, then Decision, Rejected alternatives, Consequences, optional Verification, Related. Number functional requirements R1–Rn, non-functional NR1–NRn, constraints C1–Cn, cross-cutting challenges CC1–CCn.
  • Ordering: Use numbered prefixes for file names (e.g., 01-modular-monolith.md, 02-ports-and-adapters.md) to enforce a logical reading order.
  • Index Maintenance: Whenever you add or remove a document in this directory, you MUST update the 00-index.md file to reflect the change.
  • VitePress Configuration: Whenever you add a new document, you MUST also update the sidebar in docs/.vitepress/config.mts so it appears in the documentation site navigation.
  • Publish: After index/sidebar edits, run pnpm run docs:deploy from the repo root and push main so tngl.sh picks up site/ (see ADR 06).
  • Terminology: Strictly adhere to the Glossary (Ubiquitous Language) and:
    • Use "content-level sharing" (not row-level).
    • Use "Modular Monolith" (not microservices).
    • Use "Sidecar" for the local agent and "Global Triangle" for the cloud nodes.
    • Use Drive for the user-scoped storage root in product-facing and API vocabulary (see ADR 16); do not introduce new public Vault naming.
    • When adding ADR-local acronym glossaries, link to the central glossary for shared terms (DID, PDS, Drive, hosting topology).
  • Linting: All files must pass markdownlint. Run pnpm run lint:md from the project root before committing.

🎯 Purpose of this Directory ​

Do not put implementation details (like API endpoint routes or database schemas) in this directory. This directory is strictly for high-level system design, module boundaries, and architectural patterns (like Ports and Adapters).