Domain-Driven Folder Structure Standard¶

Purpose¶

Organizing a flat-file system for 100 people and thousands of documents requires strict discipline. If you just say "make folders," you will end up with a digital landfill in 3 months.

You need a structure that balances Human Browsability (finding things via the sidebar) with Machine Parseability (AI inferring context from the path).

This document defines the Domain-Driven Folder Structure optimized for the Git-Wiki stack.

System Architecture

For details on the technical architecture of the Git-Wiki system, see Knowledge Base System.

1. The High-Level Directory Tree¶

Do not organize by "Team" (e.g., /marketing, /dev-squad-a). Teams change names every 6 months. Organize by Domain (Stable Business Functions).

/knowledge-base
├── mkdocs.yml              # The Site Config
├── .github/                # CI/CD Workflows
│
└── content/                # The Actual Docs
    │
    ├── 00_governance/      # Global Rules (Policies, Handbook)
    │   ├── policies/       # "Must Do"
    │   └── standards/      # "Should Do"
    │
    ├── 01_architecture/    # The "Graph" Index (System definitions)
    │   ├── systems/        # High-level System/Capability docs
    │   └── catalogs/       # Data Dictionaries, API Specs
    │
    ├── 10_commercial/      # Sales, Marketing, Dealers
    │   ├── dealer-network/ # A specific System context
    │   └── distributors/
    │
    ├── 20_operations/      # Logistics, Physical Retail, Finance
    │   ├── inventory/
    │   └── warehouse/
    │
    ├── 30_product/         # The Software/App Product
    │   ├── grading-app/
    │   └── marketplace/
    │
    ├── 90_records/         # Immutable History (Don't edit past files)
    │   ├── adr/            # Architecture Decision Records
    │   └── post-mortems/   # Incident Logs
    │
    └── assets/             # Global images/PDFs

2. The "Atomic Unit" (The Leaf Folders)¶

For 100 people, you cannot just dump .md files into the Domain folders. You need a consistent "Bundle" structure.

Inside a specific domain (e.g., /20_operations/inventory/), organize by Information Type.

/20_operations/
└── inventory/                  # The System/Context
    ├── index.md                # The "Home Page" for Inventory
    │
    ├── sops/                   # "How-To" (Procedural)
    │   ├── sop-intake.md
    │   └── sop-cycle-count.md
    │
    ├── reference/              # "What Is" (Declarative)
    │   ├── sku-naming-convention.md
    │   └── box-sizes.md
    │
    ├── troubleshooting/        # "Fix It" (Diagnostic)
    │   └── scanner-errors.md
    │
    └── _assets/                # Images specific to Inventory
        └── scanner-diagram.png

Why this works for AI:

When the Go Service ingests sop-intake.md, it looks at the path: operations/inventory/sops/.
Inference: It knows this is an SOP related to Inventory within Operations. It doesn't need you to tag it manually; the folder structure is the tag.

3. The "100-Person" Rules of Engagement¶

To prevent chaos, you enforce these rules via Linter (CI/CD) or Pre-commit Hooks.

Rule A: The "Colocation" Rule (Images)¶

Never put images in a giant top-level /images folder.

Bad: /images/screenshot_final_v2.png (Who owns this?)
Good: /20_operations/inventory/_assets/scanner.png
Why: When you delete the Inventory folder, the images get deleted too. No orphans.

Rule B: The "Slug" Filename Convention¶

Humans write titles; Machines read slugs.

Title: "How to Run Friday Night Magic (Updated 2025)"
Filename: run-fnm-event.md
Constraint: Lowercase, kebab-case, no spaces, no dates (unless it's a record).

Rule C: The "Index" Requirement¶

Every folder must have an index.md.

This ensures that when a user clicks "Inventory" in the sidebar, they see a landing page, not a 404 or a raw file listing.
AI Use Case: The index.md should contain the System Definition that links to your Graph.

Example: /20_operations/inventory/index.md

---
id: "sys-inventory"
type: System
owner: "[[role-ops-manager]]"
---
# Inventory System
This section contains all SOPs and guides regarding stock management.

4. Handling "Records" vs. "Evergreen"¶

This is the biggest mistake large teams make. They mix History with Truth.

Evergreen (The Wiki): "How to deploy code." (Edited constantly).
Records (The Log): "Why we chose Go vs Rust." (Written once, never edited).

The Implementation: Move all Records to the 90_records folder and require Dates in filenames.

/90_records/adr/001-use-postgres.md
/90_records/incidents/2025-11-21-db-outage.md

AI Benefit: When the AI answers a question, it prioritizes Evergreen folders for "How to" questions, and Records folders for "History/Context" questions.

5. The "Drafts" Workflow (Private vs. Public)¶

With 100 people, you don't want half-baked drafts confusing the AI.

The _drafts Folder:

Create a _drafts folder at the root.
Configure MkDocs and your Go Ingestion Script to IGNORE any folder starting with _.
When a draft is ready, the user moves it to the correct Domain folder.

Summary: The "Path-to-Context" Map¶

If you use this structure, your file path tells the AI everything it needs to know about the document.

content / {DOMAIN} / {SYSTEM} / {TYPE} / {FILE}

Example Path: content/operations/inventory/sops/sop-intake.md

AI Interpretation:

Domain: Operations
System: Inventory
Type: SOP (Standard Operating Procedure)
Topic: Intake

This gives you high-precision retrieval without forcing your team to write complex metadata tags for every single file.