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

The repository has two top-level content trees with distinct build pipelines:

domus-captures/
├── docs/modules/ROOT/           # Antora pipeline → Cloudflare Pages
│   ├── pages/                   #   Published content
│   ├── partials/                #   Reusable fragments (partial$)
│   ├── examples/                #   Code snippets (example$)
│   └── images/                  #   Media assets
├── data/                        # Standalone pipeline → build-adoc.sh
│   ├── shared/                  #   Domain-agnostic references & partials
│   │   ├── partials/            #     Reusable fragments (relative includes)
│   │   ├── templates/           #     Document scaffolds
│   │   └── attributes.adoc      #     Shared attributes for data/ builds
│   ├── d000/                    #   Personal domain (home lab, personal)
│   │   ├── infra/               #     Lab queries, runbooks
│   │   │   ├── partials/        #       Lab-specific partials
│   │   │   └── output/          #       Rendered HTML/PDF
│   │   ├── personal/            #     Legal, medical (encrypted .age)
│   │   ├── projects/            #     Personal project artifacts
│   │   └── sessions/            #     Claude Code session captures
│   ├── d001/                    #   Work domain
│   │   ├── api/                 #     Validated API pattern library
│   │   ├── investigations/      #     Ad-hoc investigations
│   │   ├── projects/            #     Work project artifacts
│   │   ├── comms/               #     Team communications (encrypted)
│   │   └── cr-baseline/         #     Change request data
│   └── spanish/                 #   Language learning data
├── scripts/                     # Build and generation automation
├── Makefile                     # Antora build orchestration
└── antora-playbook.yml          # Antora source configuration

Antora Content Tree

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/

Build Pipelines

domus-captures operates two independent build pipelines. Each serves a different purpose and produces output in a different location.

Antora Pipeline (Published)

Source

docs/modules/ROOT/

Tooling

Antora 3.1 + Kroki + Lunr search

Build command

make or npx antora antora-playbook.yml

Output

build/site/ → Cloudflare Pages

Deploy

Push to GitHub → auto-build via domus-docs hub

Include macros

partial$, example$, xref:

Attributes

docs/modules/ROOT/partials/attributes.adoc (via include::partial$attributes.adoc[])

Content in docs/ is the published chronicle — worklogs, standards, patterns, codex, case studies. It goes through the Antora aggregation model and appears on docs.domusdigitalis.dev/captures/.

Standalone Pipeline (Operational)

Source

data/*/.adoc

Tooling

domus-asciidoc-build (Asciidoctor + Rouge + docinfo variants)

Build command

build-adoc.sh <file> html --variant catppuccin

Output

<source-dir>/output/ (sibling to source file)

Deploy

Local only — not published

Include macros

Relative paths only (include::../../shared/partials/prereqs-credentials.adoc[])

Attributes

data/shared/attributes.adoc (via relative include or -a flags)

Content in data/ is operational — API references, investigation queries, encrypted artifacts, project working data. It is built on-demand for local use and never enters the Antora pipeline.

Pipeline Boundaries

Rule Antora (docs/) Standalone (data/)

Include syntax

include::partial$name.adoc[]

include::../../shared/partials/name.adoc[]

Attribute source

partials/attributes.adoc

data/shared/attributes.adoc

Cross-references

xref:page.adoc[]

Standard AsciiDoc [anchor] only

Output location

build/site/

<source-dir>/output/

Encrypted content

Never included (.age files are opaque)

Adjacent — plaintext partials reference encrypted siblings

Shared partials

docs/modules/ROOT/partials/

data/shared/partials/

Key constraint: The two pipelines do NOT share partials. docs/ partials use Antora macros; data/ partials use relative paths. A partial written for one pipeline will not resolve in the other. If content must appear in both, maintain two copies or extract to a format both can consume.

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[].

  9. Files under data/ MUST NOT use Antora include macros (partial$, example$). Standalone builds use relative paths only.

  10. Standalone build output MUST be written to an output/ directory sibling to the source file, never to build/site/.

  11. Shared partials for data/ builds MUST live in data/shared/partials/. They MUST NOT depend on Antora attributes or macros.

  12. Encrypted .age files MUST NOT be included by any build pipeline. Plaintext partials MAY reference encrypted siblings by path for documentation purposes.

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 (Antora)

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

Zero output

Build clean (standalone)

build-adoc.sh <file> html --variant catppuccin 2>&1 | grep -E 'WARN|ERROR'

Zero output

No Antora macros in data/

grep -r 'partial\$|example\$' data/

Zero matches

Standalone output isolation

find data/ -name 'output' -type d — all under source dirs

No output dirs outside data/

Exceptions

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

Related