STD-009: Repository Architecture

The canonical structure of domus-captures as a documentation system. This standard defines the purpose, scope, architecture, nav hierarchy, directory skeleton, and content type relationships. It is the replicable blueprint — anyone (or any AI agent) reading this standard can reconstruct the system from scratch with zero deviation.

Abstract

domus-captures is the personal and professional knowledge capture system of Evan Rosado — a senior infrastructure and security engineer. It is one of 15 spoke repositories aggregated through Antora into Domus Digitalis, a single documentation site deployed via Cloudflare Pages.

Purpose

domus-captures exists to:

  1. Capture daily work — worklogs, meeting notes, session transcripts, and operational records create an audit trail and daily rhythm.

  2. Codify knowledge — patterns, codex entries, and standards transform experience into reusable, transferable knowledge.

  3. Track projects — from workstation deployments to software tools, every project follows a structured lifecycle with phases, appendices, and case studies.

  4. Enforce standards — normative governance documents ensure consistency across all documentation, operations, and AI interactions.

  5. Enable learning — education tracks, training sessions, and certification study plans are integrated into the daily workflow.

Scope

In Scope Out of Scope

Daily worklogs, session captures, meeting notes

Infrastructure runbooks (domus-infra-ops)

CLI patterns, codex reference, training sessions

ISE/NAC policy documentation (domus-ise-linux, domus-ise-ops)

Project documentation (work + personal)

Secrets management procedures (domus-secrets-ops)

Case studies (TAC, INC, CR, RCA, DEPLOY)

Network API tool documentation (domus-netapi-docs)

Standards framework (STD-001+)

UI bundle and theme system (domus-antora-ui)

Education tracks and certifications

Hub aggregator configuration (domus-docs)

Strategic objectives and meta-systems

Windows domain operations (domus-windows-ops)

Spoke-Hub Model

Spoke repos (15)                    Hub repo (1)
├── domus-captures    ──push──►     domus-docs
├── domus-infra-ops   ──push──►       ├── antora-playbook.yml
├── domus-ise-linux   ──push──►       ├── ui-bundle.zip
├── domus-netapi-docs ──push──►       └── (aggregates all spokes)
├── domus-secrets-ops ──push──►              │
├── domus-antora-ui   ──push──►              ▼
├── domus-ise-ops                    Cloudflare Pages
├── domus-linux-ops                  https://docs.domusdigitalis.dev
├── domus-windows-ops
├── domus-automation-ops
├── domus-identity-ops
├── domus-o11y-ops
├── domus-python
├── domus-musica
└── ollama-local

Deployment rule: Push any spoke repo → Cloudflare Pages auto-builds. Push domus-docs ONLY when changing antora-playbook.yml or ui-bundle.zip.

Component Identity

Field Value

Antora component name

captures

Antora title

Work Chronicles

Start page

ROOT:index.adoc

Category

Core

Nav order

2

Deploy target

docs.domusdigitalis.dev/captures/

Principles

  1. Separation by intent. Content is organized by what it IS, not when it was created. Standards are prescriptive. Patterns are descriptive. Codex is referential. Projects are iterative. They live in different sections because they serve different purposes.

  2. Partials hold content, pages are shells. This applies to projects (STD-001), standards, and any content that benefits from composability. Container pages provide metadata; partials provide substance.

  3. Nav reflects information architecture. The navigation order is deliberate: strategy → governance → learning → knowledge → execution → meta. Each section is extracted to a partial for maintainability.

  4. Spoke-hub deployment. domus-captures is a spoke repository in the Antora aggregation model. Push this repo; Cloudflare Pages builds automatically via domus-docs (the hub). Push domus-docs only when changing antora-playbook.yml or the UI bundle.

  5. Chronological AND categorical. Time-series content (worklogs, sessions) lives in YYYY/MM/ directories. Categorical content (patterns, codex, standards) lives in named directories. Both are valid organizing principles for different content types.

Repository Skeleton

docs/modules/ROOT/
├── pages/
│   ├── standards/             # Normative governance (STD-NNN)
│   │   ├── operations/        #   Change control, validation, RCA, incident response
│   │   ├── documentation/     #   Project structure, file naming, AsciiDoc, repo architecture
│   │   ├── security/          #   Secrets handling
│   │   ├── ai-interaction/    #   Delegation boundary
│   │   └── workflow/          #   CLI quality
│   ├── objectives/            # Strategic direction — certifications, career, life
│   ├── patterns/              # Experiential knowledge (Aristotelian taxonomy)
│   │   ├── text/              #   awk, sed, grep, regex, jq, xargs
│   │   ├── shell/             #   Process substitution, parameter expansion
│   │   ├── vim/               #   Registers, macros, substitution
│   │   ├── git/               #   Branching, rebase, multi-remote
│   │   ├── networking/        #   tcpdump, DNS, wireless, firewall
│   │   ├── security/          #   PKI, Vault, EAP-TLS, KQL
│   │   ├── infrastructure/    #   systemd, LUKS, KVM, Borg, Stow
│   │   ├── operations/        #   Change mgmt, RCA, prioritization
│   │   ├── career/            #   Incident response, vendor mgmt, negotiation
│   │   ├── api/               #   REST, curl, ISE, Vault API
│   │   ├── python/            #   CLI, API, data processing
│   │   ├── documentation/     #   AsciiDoc, Antora, xrefs
│   │   ├── ai/                #   Claude Code, skills, hooks, agents
│   │   ├── mathematics/       #   Algebra, notation
│   │   ├── language/          #   Spanish, Latin
│   │   ├── music/             #   LilyPond, theory
│   │   ├── literature/        #   Don Quijote, reading methods
│   │   └── navigation/        #   Map reading
│   ├── codex/                 # CLI reference blocks ("The Arsenal")
│   │   ├── text/              #   awk, sed, jq, grep, xargs, regex
│   │   ├── bash/              #   Streams, pipes, variables, loops
│   │   ├── vim/               #   Motions, registers, macros
│   │   ├── git/               #   Basics through worktrees
│   │   ├── linux/             #   Files, processes, systemd, disk
│   │   ├── networking/        #   Diagnostics, curl, SSH, dig
│   │   ├── security/          #   DataConnect, passwords, certs
│   │   ├── python/            #   CLI, requests, files
│   │   ├── powershell/        #   AD, remoting, certificates
│   │   ├── containers/        #   Docker, Podman, kubectl
│   │   ├── gopass/            #   Secrets management tool
│   │   ├── assembly/          #   x86 fundamentals
│   │   ├── iac/               #   Terraform
│   │   ├── languages/         #   Lua
│   │   ├── kql/               #   Sentinel queries
│   │   ├── claude/            #   AI tool patterns
│   │   └── quickref/          #   Shortcuts, exit codes
│   ├── projects/              # Project documentation (STD-001 structure)
│   │   ├── chla/              #   Work projects
│   │   └── personal/          #   Personal projects
│   ├── case-studies/          # Operational records
│   │   ├── tac/               #   Vendor TAC cases
│   │   ├── incidents/         #   INC- reports (STD-011)
│   │   ├── changes/           #   CR- change records
│   │   ├── rca/               #   RCA- root cause analyses (STD-010)
│   │   └── deployments/       #   DEPLOY- records
│   ├── education/             # Learning tracks
│   │   ├── rhcsa/             #   RHCSA certification
│   │   ├── cissp/             #   CISSP 57-day plan
│   │   ├── literature/        #   Don Quijote, reading
│   │   ├── math/              #   Algebra, problem sets
│   │   └── programming/       #   Assembly, Rust, Python
│   ├── portfolio/             # Project portfolio (70+ entries, 12 categories)
│   ├── discoveries/           # Micro-learning captures (tools, system, workflow)
│   ├── sessions/              # Claude Code session captures
│   ├── YYYY/MM/               # Chronological captures (WRKLOG, MTG, DOC, REF, LRN)
│   ├── reference/             # Evergreen reference material
│   │   ├── commands/          #   Command favorites and deep dives
│   │   ├── diagrams/          #   Architecture, network, security galleries
│   │   ├── math/              #   Graphing, networking math
│   │   ├── music/             #   CLI nerdcore, violin
│   │   └── systems/           #   Software/hardware inventories
│   ├── api/                   # API documentation hub
│   │   ├── ise/               #   5 ISE APIs
│   │   ├── vault/             #   HashiCorp Vault
│   │   └── patterns/          #   Auth, pagination, error handling
│   ├── operations/            # Operational cadence
│   │   ├── chla/              #   Work-specific operations
│   │   └── runbooks/          #   Operational runbooks
│   ├── trackers/              # Progress tracking dashboards
│   ├── meta/                  # Strategic systems
│   ├── templates/             # Document type templates
│   └── drafts/                # Work in progress
├── partials/
│   ├── standards/             # Standard content (partial+page pattern)
│   │   ├── operations/
│   │   ├── documentation/
│   │   ├── security/
│   │   ├── ai-interaction/
│   │   └── workflow/
│   ├── projects/              # Project content (partial+page pattern)
│   │   ├── thinkpad-t16g-deploy/   # 13 phases + 8 appendices (reference impl)
│   │   ├── rhel9-workstation/
│   │   ├── eve-ng-lab/
│   │   └── ...
│   ├── nav/                   # Navigation partials (7 files)
│   │   ├── standards.adoc
│   │   ├── training-sessions.adoc
│   │   ├── pattern-journal.adoc
│   │   ├── case-studies.adoc
│   │   ├── knowledge-base.adoc
│   │   ├── education.adoc
│   │   ├── chronicle-2026.adoc
│   │   └── chronicle-2025.adoc
│   ├── worklog/               # Worklog section includes
│   ├── trackers/              # Tracker content
│   ├── codex/                 # Codex snippets
│   └── attributes.adoc        # All shared attributes
└── examples/                  # Code snippets for include::example$
    ├── codex/
    ├── lab/
    ├── regex-drills/
    └── monad/

Repository Metrics

As of 2026-04-06. These numbers define the expected scale — a replicator uses them to verify their instance matches.

Metric Count Note

Total .adoc files

2,954

find docs/modules/ROOT -name '*.adoc' | wc -l

Pages (content)

~2,100

Under pages/

Partials (reusable)

~850

602 projects + 189 trackers + others

Examples (code)

~500

Under examples/

Top-level page directories

20

All defined in skeleton above

Projects documented

68

In partials/projects/

Nav partials

8

In partials/nav/

Standards

20

STD-001 through STD-020

Portfolio entries

70+

Across 12 categories

Training tracks

8

regex, jq, python, lua, nvim, etl, monad, tmux

Diagrams

77+

Across 9 categories (D2, Graphviz, Mermaid)

File Distribution by Section

Directory Files % of Pages

education/

789

26.7%

projects/

255

8.6%

codex/

110

3.7%

2026/ (chronological)

105

3.6%

patterns/

95

3.2%

portfolio/

77

2.6%

case-studies/

76

2.6%

reference/

52

1.8%

standards/

22

0.7%

templates/

20

0.7%

api/

18

0.6%

All others

~80

2.7%

Partials Deep Structure

The partials/ tree extends beyond what the skeleton shows:

partials/
├── standards/         # 15 files — STD content (partial+page pattern)
├── projects/          # 602 files — 68 project directories
├── trackers/          # 189 files — work/, personal/, education/
├── reference/         # 86 files — command-reference/, d2-styling/, diagram-tools/
├── nav/               # 8 files — navigation partials
├── worklog/           # 21 files — daily section includes
├── reports/           # 15 files — progress report content
├── codex/             # 15 files — codex snippets for inclusion
├── runbooks/          # 12 files — operational runbook content
├── tasks/             # 10 files — task tracking content
├── math/              # 10 files — formula and problem content
├── discoveries/       # 8 files — micro-learning captures (tools, system, workflow)
├── education/         # 4 files — education track partials
├── objectives/        # 2 files — strategic objective content
└── attributes.adoc    # Shared attributes (single source of truth)

Examples Library

The examples/ directory is a 500+ file library supporting include::example$ throughout the site:

examples/
├── api/               # ISE, Keycloak, OpenAI, pfSense, Synology, Vault, WLC
├── codex/             # Reference code for 15+ domains (bash, git, vim, etc.)
├── commands/          # Command-specific drills (awk, curl, dns, find, grep, jq, sed, etc.)
├── diagrams/          # D2, Graphviz, Mermaid source files (P16g boot chain, etc.)
├── terminal/          # Interactive terminal examples (ANSI, streams, scenarios)
├── math/              # 22 formula files
├── music/             # 60+ LilyPond scores (scales, arpeggios, cello, violin)
├── monad/             # jq, Python, shell, testing examples
├── navigation/        # Python coordinate/MGRS tools
├── regex-drills/      # Regex practice exercises
├── jq-drills/         # jq practice exercises
├── python-drills/     # Python practice exercises
├── lua-drills/        # Lua practice exercises
├── etl-drills/        # ETL pipeline exercises
├── lab/               # Shell experiments (brace expansion, process substitution)
├── claude/            # 28+ AI context files
├── outputs/           # ISE/Linux validation outputs
└── objectives/        # Template

Scripts Directory

The scripts/ directory at the repository root (outside docs/) contains automation tooling:

scripts/
├── sync-nav.sh                    # Synchronize nav.adoc with content
├── sync-worklog-nav.sh            # Update worklog navigation
├── update-carryover-days.sh       # Calculate days-since-origin for trackers
├── update-monthly-index.sh        # Generate monthly index pages
├── audit-worklogs.sh              # Validate worklog completeness
├── migrate-quijote.sh             # Content migration utilities
├── mdn-cleanup-macros-*.sh        # Migration cleanup scripts
└── remarkable/                    # 40+ scripts for reMarkable PDF generation
    ├── generate-*.py              # PDF generation per subject
    ├── upload-*.sh                # Device sync
    └── data/                      # Vocabulary, grammar source data

Navigation Architecture

The nav order is deliberate — it mirrors a governance hierarchy:

Position Section Purpose

1

Strategic Objectives

WHERE we’re going — certifications, career, life goals

2

Standards

HOW we enforce quality — governance layer (this framework)

3

Training Sessions

HOW we build skill — structured learning tracks

4

Pattern Journal

WHAT we’ve learned — experiential knowledge (Aristotelian taxonomy)

5

Case Studies

WHAT happened — TAC, incidents, changes, RCAs, deployments

6

Sessions

WHAT we built — Claude Code session captures

7

Chronicle

WHEN things happened — chronological worklogs

8

Knowledge Base

WHAT we know — Codex, API Hub, Commands, Reference

9

Education

WHAT we’re learning — certifications, literature, math, programming

10

Operations

HOW we run things — cadence, trackers, runbooks

11

Projects

WHAT we’re building — all projects (work + personal)

12

Meta

HOW we think about the system — strategic alignment, velocity

13

Templates

HOW to start — document type templates

14

Drafts

Work in progress — uncommitted ideas

Nav sections with >50 lines MUST be extracted to partials/nav/<name>.adoc.

Content Type Relationships

Content Type Produces Consumed By

Standards

Compliance criteria, templates

CLAUDE.md enforcement, validation runs, project checklists

Patterns

Transferable wisdom, dated entries

Standards (graduation), codex (reference extraction)

Codex

Reference cards, syntax tables

Patterns (inline reference), education (curriculum)

Projects

Deliverables, case studies

Patterns (lessons learned), RCAs (incident context)

Case Studies

Incident/change records, RCAs

Patterns (extracted wisdom), standards (process updates)

Worklogs

Daily capture, session records

Projects (progress tracking), patterns (discovery source)

Requirements

  1. The top-level directory structure MUST follow the skeleton defined above. New top-level directories require a standard update.

  2. Every nav section exceeding 50 lines MUST be extracted to a partial in partials/nav/.

  3. The nav order MUST follow the governance hierarchy: strategy → governance → learning → knowledge → execution → meta.

  4. Chronological content (worklogs, meetings, session captures) MUST use YYYY/MM/ directory structure with date-prefixed filenames (STD-003).

  5. Categorical content (patterns, codex, standards, projects) MUST use named directories organized by domain.

  6. The spoke-hub deployment model MUST be followed: push this repo for automatic Cloudflare Pages build. Push domus-docs ONLY when changing antora-playbook.yml or ui-bundle.zip.

  7. All shared attributes MUST be defined in partials/attributes.adoc and included via include::partial$attributes.adoc[].

  8. The examples/ directory MUST be used for code snippets >10 lines via include::example$category/name.sh[].

Reference Implementation

The ThinkPad P16g deployment project demonstrates maximum granularity:

partials/projects/thinkpad-t16g-deploy/
├── metadata.adoc                    # Project metadata table
├── summary.adoc                     # Status table — 13 phases + SEC findings
├── assessment.adoc                  # Pre-work risk assessment
├── phase-0-pre-arrival.adoc         # Borg backup, USB prep, gopass sync
├── phase-1-remote-access.adoc       # iPSK, WiFi, SSH
├── phase-2-disk-encryption.adoc     # 4-partition dual-LUKS, btrfs
├── phase-3-base-system.adoc         # pacstrap, fstab, crypttab
├── phase-4-bootloader.adoc          # mkinitcpio, systemd-boot
├── phase-5-first-boot.adoc          # SSH reconnect, packages, verification
├── phase-6-desktop.adoc             # GPU, Hyprland, audio, bluetooth, themes (481 lines)
├── phase-7-dotfiles.adoc            # Secrets bootstrap, stow, domus-nvim
├── phase-8-secrets.adoc             # age, SSH keys, gopass, gocryptfs
├── phase-8-eaptls.adoc              # Vault cert, nmcli WiFi EAP-TLS
├── phase-9-development.adoc         # Languages, repos, Claude Code
├── phase-10-ai-stack.adoc           # Ollama, RTX 5090, models
├── phase-11-verification.adoc       # 30+ checks across 8 domains
├── phase-12-security-hardening.adoc # AppArmor, UFW, SSH lockdown
├── phase-13-maintenance.adoc        # Borg automation, cert renewal, timers
├── appendix-scope-creep.adoc        # Discovered backlog items
├── appendix-hardware.adoc           # Hardware specs, pre-wipe baseline
├── appendix-commands-learned.adoc   # Commands discovered during project
├── appendix-deviations.adoc         # Plan vs reality divergences
├── appendix-issues.adoc             # Problems + resolutions
├── appendix-stow-audit.adoc         # 44-package stow audit
├── appendix-todos.adoc              # Post-deploy improvements
└── appendix-system-internals.adoc   # Boot chain diagrams (8 diagrams)

This is the target granularity. Every phase is independently navigable. Every appendix serves one audience. The 481-line Phase 6 is the upper bound — if a partial exceeds ~500 lines, consider splitting.

Compliance

Check Method Pass Criterion

Directory structure matches skeleton

tree -L 2 docs/modules/ROOT/pages/ compared to standard

No unauthorized top-level directories

Nav partials extracted

wc -l partials/nav/*.adoc — no inline section >50 lines in nav.adoc

Large sections in partials

Nav order correct

Visual inspection of nav.adoc include order

Matches governance hierarchy

Chronological content dated

ls pages/YYYY/MM/ — files use date prefixes

STD-003 naming enforced

Attributes centralized

grep -r 'include::partial\$attributes' pages/ — usage consistent

No hardcoded mutable values (STD-004)

Build clean

make 2>&1 | grep -E 'WARN|ERROR'

Zero output

Exceptions

None. This standard applies to domus-captures unconditionally. Other spoke repositories MAY adopt a subset of this architecture appropriate to their scope.

Related