Skip to content

ADR-001: Use Domain-Driven Folder Structure

Status

Accepted

Context

We need to organize documentation for a growing organization (targeting 100+ people) with thousands of documents. The traditional approaches we considered had significant drawbacks:

  • Team-based folders (e.g., /marketing, /dev-squad-a) - Teams reorganize frequently, leading to broken links and confusion
  • Flat structure - Becomes unmanageable at scale, hard to browse
  • Type-based folders (e.g., /sops, /references) - Loses domain context, hard to find related documents
  • No structure - Complete chaos, relies entirely on search

We need a system that: 1. Supports both human browsability and AI-powered search 2. Encodes context in the file path itself 3. Scales to thousands of documents 4. Remains stable despite organizational changes 5. Works well with git-based workflows

Decision

We will adopt a domain-driven folder structure where:

  1. Top-level organization by stable business domains, not teams:
  2. 00_governance/ - Policies and standards
  3. 01_architecture/ - System definitions and catalogs
  4. 10_commercial/ - Sales, marketing, dealers
  5. 20_operations/ - Logistics, warehouse, inventory
  6. 30_product/ - Product documentation

  7. 90_records/ - Immutable historical records

  8. Second level by system/context within each domain:

  9. Example: /20_operations/inventory/

  10. Third level by information type:

  11. sops/ - "How-To" procedural guides
  12. reference/ - "What Is" declarative information

  13. troubleshooting/ - "Fix It" diagnostic guides

  14. Path-to-context encoding:

  15. File path format: {DOMAIN}/{SYSTEM}/{TYPE}/{FILE}
  16. Example: 20_operations/inventory/sops/sop-intake.md

  17. AI can infer: Domain=Operations, System=Inventory, Type=SOP, Topic=Intake

  18. Mandatory index files:

  19. Every folder must have an index.md

  20. Serves as landing page and system definition

  21. Asset colocation:

  22. Images stored in _assets/ within each system
  23. Prevents orphaned files

  24. Clear ownership

  25. Draft isolation:

  26. _drafts/ folder excluded from build and AI indexing
  27. Prevents incomplete docs from causing confusion

Consequences

Positive

  • Scalable: Structure remains clear even with thousands of documents
  • AI-friendly: File path provides rich context without manual tagging
  • Stable: Domains change less frequently than teams
  • Browsable: Clear hierarchy for human navigation
  • Maintainable: Clear ownership, easy to delete unused sections
  • Search-optimized: Context helps AI provide more precise answers

Negative

  • Learning curve: New contributors need to understand the structure
  • Rigid: Must follow conventions strictly for AI benefits
  • Migration effort: Existing docs need to be reorganized
  • Enforcement needed: Requires linting or CI checks to maintain

Mitigation Strategies

  • Document the structure clearly (this ADR + governance standards)
  • Provide templates and examples
  • Add linting to CI/CD pipeline
  • Train new team members on the structure

Alternatives Considered

Alternative 1: Flat structure with heavy tagging

Use a flat folder structure with extensive YAML frontmatter tags.

Rejected because: - Requires manual tagging of every document - Tags often become inconsistent over time - Poor browsability for humans - Frontmatter can become complex and burdensome

Alternative 2: Wiki-style with categories

Use a MediaWiki or Confluence-style category system.

Rejected because: - Requires specialized wiki software - Not git-friendly - Categories often multiply uncontrollably - Hard to enforce consistency

Alternative 3: Alphabetical folders

Simple A-Z folder structure.

Rejected because: - No semantic organization - Loses domain context - Doesn't scale well - Poor AI inference

References

Implementation Notes

  • MkDocs configured with docs_dir: content
  • Excluded _drafts/ and */_assets/ from navigation
  • Material theme provides good navigation UI
  • CI will eventually enforce index.md requirements