Zettle

0008-folder-structure

2 min read

ADR-0008: Folder structure — flat per type, mirrors URLs

Status: Accepted Date: 2026-05-19

Context

Need a layout that’s easy to navigate by hand, easy for AI to enforce rules against, and mirrors cleanly to published URLs.

Decision

Flat per type. No topical sub-folders within /reference/, /threads/, /questions/, etc. Tags + backlinks do topical slicing; folders only sort by type.

/
├── CONTEXT.md              # rulebook — root for visibility
├── README.md               # vault intro
├── resources-raw/          # gitignored — large/copyrighted PDFs
├── resources/{DP,CSG,Bible,SMM,Transcripts}/
├── reference/              # textual atomics — flat
├── experience/             # experiential atomics — flat
├── threads/                # flat
├── questions/              # flat
├── persons/                # flat (thin indexes)
├── glossary/               # flat
├── sermons/{pastoral,worship-redirect}/
├── staging/                # ephemeral batches under review
├── scripts/                # Python pipeline (added in Phase 5)
└── _meta/
    ├── tags.md             # closed tag registry
    ├── rejected-proposals.md   # AI doesn't re-suggest these
    └── adr/                # decisions log (these files)

Published URLs mirror this folder structure exactly (/reference/fall-as-misuse-of-love). No transformation; what you see in the vault is what visitors see.

Alternatives considered

  • Topical sub-folders (e.g. /reference/fall/, /reference/restoration/): rejected — a single atomic on the Fall also touches free will, love, sin; folders force one home, tags don’t. Zettelkasten orthodoxy.
  • Flatter URL scheme on the site (/notes/...): rejected — adds a layer of translation between vault and site for no clear benefit.
  • CONTEXT.md in /_meta/: rejected — most-read file in the vault deserves root visibility.

Consequences

  • (+) Adding a note is unambiguous (provenance + type → exactly one folder)
  • (+) URL structure is predictable for external readers and AI
  • (+) Pre-commit hook can rely on folder == type for validation
  • (−) Folders aren’t a navigation aid when scanning by topic (tags + graph fill this gap)

Graph View