Vault Structure and Organization

A well-organized vault is critical for long-term maintainability. This guide explains the folder structure, naming conventions, and organizational principles used in the Garage Project.

Core Organizational Principles

1. Numeric Prefixes for Ordering

Use numeric prefixes to control folder display order:

00-Index.md           # Always appears first
10-Planning/          # Planning phase
20-Design/            # Design phase
30-Vendors & Contacts/  # External parties
40-Meetings/          # Chronological meetings
50-Build/             # Construction/execution
60-After Build/       # Post-completion
90-Reference/         # Reference materials

Why this works:

Folders appear in logical project order
Easy to add new phases (15-, 25-, 35-, etc.)
Immediately clear which phase a folder belongs to
Works in any file browser, not just Obsidian

2. Phase-Based Organization

Organize by project phase, not by content type:

✅ Good (Phase-based):

10-Planning/
  ├── Budget.md
  ├── Timeline.md
  └── Permits.md
20-Design/
  ├── Floor Plan.md
  └── Electrical.md

❌ Avoid (Type-based):

Documents/
  ├── Budget.md
  ├── Floor Plan.md
Images/
  └── ...
PDFs/
  └── ...

Rationale: Projects progress through phases. Grouping by phase keeps related information together and makes the project lifecycle clear.

3. Meaningful Names, Not Abbreviations

Use full, descriptive names:

✅ Good:

Vendors & Contacts/
Electrical Planning.md
HVAC Strategy.md

❌ Avoid:

V&C/
Elec_Plan.md
hvac_strat.md

Why: You read document names far more than you type them. Clarity beats brevity.

Garage Project Structure

Here’s the complete vault structure from the Garage Project:

Garage/
├── content/                          # Web publishing content root
│   ├── index.md                      # Main project homepage (web)
│   ├── 00-Index.md                   # Obsidian dashboard
│   ├── 10-Planning/
│   │   ├── To-Do.md
│   │   ├── Timeline.md
│   │   ├── Decisions Log.md
│   │   ├── Decisions - [Specific Topic].md
│   │   ├── Budget.md
│   │   └── Permits & Zoning.md
│   ├── 20-Design/
│   │   ├── Interior/
│   │   │   ├── HVAC Strategy.md
│   │   │   ├── Electrical Planning.md
│   │   │   ├── Insulation.md
│   │   │   └── Lift.md
│   │   └── Exterior/
│   │       ├── Siding.md
│   │       └── Roofing.md
│   ├── 30-Vendors & Contacts/
│   │   ├── Products Used.md         # Product catalog (newly added)
│   │   ├── Services/
│   │   │   ├── General Contractors.md
│   │   │   ├── HVAC Contractors.md
│   │   │   └── Electrical Contractors.md
│   │   └── Orders/
│   │       ├── Orders Index.md
│   │       ├── Mini-Split HVAC Order.md
│   │       └── Boiler and Radiant Order.md
│   ├── 40-Meetings/
│   │   ├── 2025-02-04 - Meeting - Integral Builders.md
│   │   ├── 2025-02-27 - Meeting - Jonas Hershberger.md
│   │   └── 2025-10-13 - Contract Signing.md
│   ├── 50-Build/
│   │   ├── Initial Build.md
│   │   ├── Construction Videos.md
│   │   ├── Utilities & Conduits.md
│   │   └── Mechanical Room.md
│   ├── 60-After Build/
│   │   └── After initial build.md
│   ├── 90-Reference/
│   │   ├── Home Theater.md
│   │   └── Documentation System Guide/    # This guide!
│   │       ├── 00 - Overview.md
│   │       ├── 01 - Obsidian Setup.md
│   │       └── ...
│   ├── pictures/
│   │   ├── PXL_20251020_181223482.jpg
│   │   ├── PXL_20251020_181223482.md
│   │   └── ...
│   ├── Email Imports/
│   │   ├── Hershberger's Contract.md
│   │   └── Delivery invoice for hydronic heating.md
│   ├── ChatGPT Summaries/
│   │   └── Various AI-generated summaries
│   ├── Templates/
│   │   ├── Meeting.md
│   │   ├── Vendor.md
│   │   └── Order.md
│   ├── CLAUDE.md                     # AI assistant instructions
│   └── Sequence to build garage.md
├── quartz/                            # Quartz web publishing
├── .git/                              # Git version control
└── .obsidian/                         # Obsidian configuration

Folder-by-Folder Breakdown

`00-Index.md` and `index.md`

Two index files serve different purposes:

00-Index.md: Full-featured Obsidian dashboard

Dataview queries showing active tasks
Meeting timelines
Decision logs
Only works in Obsidian (uses plugins)

index.md (in content/ root): Web-friendly homepage

Simplified project overview
No plugin dependencies
Becomes the homepage when published with Quartz
Clean presentation for stakeholders

Example from Garage Project:

index.md includes:

## Current Build Status
**Latest milestone (Oct 22, 2025):**
- ✓ Under-slab insulation complete (2" Creatherm R-10)
- ✓ PEX radiant heating loops installed
- ⧗ Pressure testing in progress
 
## Key Contacts & Materials
See [[30-Vendors & Contacts/Products Used]] for detailed specifications

`10-Planning/` - Planning Phase

Purpose: Documents created before construction begins

Contents:

Timeline.md: Chronological project history
To-Do.md: Active tasks and pending items
Decisions Log.md: Major project decisions
Decisions - [Topic].md: Detailed decision documentation
Budget.md: Financial planning
Permits & Zoning.md: Regulatory requirements

Example Document (Decisions Log.md):

---
title: Decisions Log
type: decision
tags: [decisions]
---
 
# Project Decisions
 
| Date | Area | Decision | Status | Source |
|------|------|----------|--------|--------|
| 2025-10-22 | Foundation | Floor grading: lift bay level, other 2 bays graded | ✅ Approved | [[40-Meetings/2025-10-22 - Site Visit]] |
| 2025-10-22 | HVAC | Install ½" PEX conduit for slab sensor | ✅ Approved | [[10-Planning/Decisions - Slab Sensor Conduit]] |

Naming Convention for Decision Docs:

Log: Decisions Log.md (index of all decisions)
Details: Decisions - [Topic].md (deep dive on specific decision)

`20-Design/` - Design Specifications

Purpose: Technical specifications and design documents

Organization:

20-Design/
├── Interior/
│   ├── HVAC Strategy.md
│   ├── Electrical Planning.md
│   ├── Insulation.md
│   └── Lift.md
└── Exterior/
    ├── Siding.md
    └── Roofing.md

When to use subdirectories: When you have 5+ documents in a category

Example Document (HVAC Strategy.md):

---
title: HVAC Strategy
type: design
tags: [design, hvac, mini-split]
status: planning
---
 
## Proposed System
- Outdoor: Mitsubishi MXZ Hyper-Heat
- Garage head: ceiling cassette
- Loft head: wall-mounted unit
- Radiant slab: gas boiler
 
## Actions
- [ ] Perform Manual J load calculation
- [ ] Select head types

`30-Vendors & Contacts/` - External Parties

Purpose: Vendor information, orders, and products

Organization:

30-Vendors & Contacts/
├── Products Used.md          # Centralized product catalog
├── Services/
│   ├── General Contractors.md
│   ├── HVAC Contractors.md
│   └── Electrical Contractors.md
└── Orders/
    ├── Orders Index.md       # Dataview query of all orders
    ├── [Order Name].md
    └── ...

Products Used.md (New addition):

Complete catalog of all products
Manufacturer links
Specifications
Related documents
See Products Used for full example

Order Documents use rich frontmatter:

---
title: Mini-Split HVAC Order
type: order
vendor: TBD
order_id:
status: planning
stage: 6
key_dates:
  quoted:
  ordered:
  delivered:
totals:
  subtotal:
  total:
---

`40-Meetings/` - Meeting Documentation

Purpose: Chronological meeting notes

Naming Convention: YYYY-MM-DD - [Type] - [Subject].md

Examples:

2025-02-04 - Meeting - Integral Builders.md
2025-10-13 - Contract Signing - Hershberger.md
2025-09-05 - Site Staking - Marcus + Concrete.md

Why date prefix: Chronological sorting in file browser

Standard Structure:

---
title: 2025-10-13 - Contract Signing
type: meeting
date: 2025-10-13
attendees: [Dan, Marcus]
tags: [meeting, contract]
---
 
## Attendees
- Dan Gahagan
- Marcus (Hershberger's)
 
## Discussion
[Meeting notes]
 
## Decisions Made
- Locked in concrete specifications
- Agreed on timeline
 
## Action Items
- [ ] Submit deposit
- [ ] Review electrical plan
 
## Related Documents
- [[Email Imports/Hershberger's Contract]]

`50-Build/` - Construction Phase

Purpose: Active construction documentation

Contents:

Initial Build.md: Main construction log
Construction Videos.md: Time-lapse video documentation
Utilities & Conduits.md: Infrastructure details
Mechanical Room.md: Equipment planning

Example: Initial Build.md serves as construction journal:

## Construction Progress (Updated 2025-10-22)
- ✓ Excavation completed (Oct 20)
- ✓ 2" Creatherm under-slab insulation installed
- ✓ PEX radiant heating loops installed
- ⧗ Pressure testing radiant system at 60-70 PSI
- ⧖ Pending: Concrete slab pour

Construction Videos.md (Innovation):

Embedded YouTube time-lapse videos
Progress documentation
Shareable progress updates

`60-After Build/` - Post-Construction

Purpose: Items to complete after construction

Contents:

Punch list items
Warranty documentation
Maintenance schedules
Future enhancement ideas

`90-Reference/` - Reference Materials

Purpose: Information that doesn’t fit elsewhere

Contents:

Research and background reading
Industry standards
Product catalogs
This Documentation System Guide!

Naming: 90- ensures it appears last, as it’s supporting material

`pictures/` - Photo Documentation

Organization:

pictures/
├── PXL_20251020_181223482.jpg
├── PXL_20251020_181223482.md     # Description document
├── PXL_20251021_132453157.jpg
├── PXL_20251021_132453157.md
└── ...

Pattern: Each photo has a matching .md file with:

Detailed description
Context and significance
Technical details
Related documents

Example (PXL_20251022_190752216.md):

---
title: Radiant Heating System Pressure Test Gauge
type: photo-documentation
date: 2025-10-22
time: 19:07
phase: foundation
tags: [construction, radiant-heat, pressure-test]
---
 
# Radiant Heating System Pressure Test Gauge
 
![Pressure Test Gauge](PXL_20251022_190752216.jpg)
 
## Description
Close-up of pressure gauge reading 60-70 PSI during system test.
 
## Significance
Critical quality checkpoint before concrete pour...
 
## Related Documents
- [[50-Build/Initial Build]]
- [[20-Design/Interior/HVAC Strategy]]

See: Photo Documentation for workflow

`Email Imports/` - External Documents

Purpose: Documents that originated outside the vault

Contents:

Contracts
Invoices
Quotes
Email correspondence

Convention: Convert to markdown, preserve original information

Example:

---
title: Hershberger's Contract
type: vendor
tags: [contract, hershberger]
date: 2025-10-13
total_amount: 68400.00
---
 
# Hershberger's Amish Builders — Garage Proposal
 
**Date:** October 13, 2025
[Full contract details...]

`Templates/` - Document Templates

Purpose: Reusable document structures

Organization:

Templates/
├── Meeting.md
├── Vendor.md
├── Order.md
└── Decision.md

See: Creating Templates

`CLAUDE.md` - AI Assistant Instructions

Purpose: Instructions for AI assistants working with the vault

Contents:

Project overview
Vault structure explanation
Document types
Naming conventions
Common operations

Example:

# CLAUDE.md
 
This file provides guidance to Claude Code when working with this repository.
 
## Project Overview
Obsidian vault for managing a garage construction project...
 
## Repository Structure
- **10-Planning/**: Project planning documents
- **20-Design/**: Design specifications
[etc...]
 
## Document Types
- `type: meeting` - Meeting notes
- `type: vendor` - Vendor information
[etc...]

Why this matters: AI assistants can read this file to understand your vault structure and conventions, providing better assistance.

File Naming Conventions

General Principles

Use descriptive names: HVAC Strategy.md not hvac.md
Capitalize properly: Electrical Planning.md not electrical planning.md
Avoid special characters: Use letters, numbers, spaces, hyphens
Be consistent: Pick a convention and stick to it

Specific Patterns

Meetings: YYYY-MM-DD - Type - Subject.md

2025-10-13 - Contract Signing - Hershberger.md
2025-09-05 - Site Visit - Concrete Crew.md

Decisions: Decisions - [Topic].md or Decisions Log.md

Decisions Log.md                    # Index of all decisions
Decisions - Slab Sensor Conduit.md  # Specific decision details
Decisions - Floor Grading.md        # Specific decision details

Orders: [Product/Service] Order.md

Mini-Split HVAC Order.md
Radiant Slab Materials Order.md
Electrical Materials Order.md

Photos: Match the photo filename

PXL_20251022_190752216.jpg
PXL_20251022_190752216.md

References: Descriptive topic names

Home Theater.md
Garage Door Openers Comparison.md

Tag Strategy

Use tags sparingly and consistently:

Tag Categories

Document Type (usually in frontmatter type: field):

meeting, vendor, order, design, build, reference

Project Phase:

planning, design, construction, completed

Topic Area:

hvac, electrical, insulation, foundation, roofing, siding

Status:

active, pending, completed, cancelled

Tag vs. Folder

Use folders for: Primary organization, project phases Use tags for: Cross-cutting themes, searchability

Example: HVAC-related documents might be in:

20-Design/Interior/HVAC Strategy.md
30-Vendors & Contacts/Orders/Mini-Split HVAC Order.md
40-Meetings/2025-03-15 - HVAC Contractor Meeting.md

All tagged #hvac for easy discovery.

Scaling Your Structure

Starting Small

If your project is simpler, start with:

00-Index.md
10-Planning/
30-Vendors & Contacts/
50-Execution/
90-Reference/

Add folders as needed.

Growing Large

For complex projects, add:

Subdirectories within main folders
Intermediate numbers (15-, 25-, 35-)
Project-specific phases

Example (Software Project):

10-Planning/
20-Requirements/
30-Architecture/
40-Development/
50-Testing/
60-Deployment/
70-Maintenance/
90-Reference/

Common Pitfalls to Avoid

❌ Deep nesting: Limit to 2-3 levels maximum ❌ Redundant folders: Don’t create folders with only 1-2 files ❌ Inconsistent naming: Pick a convention, stick to it ❌ Too many tags: More than 5-6 tags per document reduces usefulness ❌ Abbreviations: Future you won’t remember what they mean

Migration and Reorganization

It’s okay to reorganize! Obsidian makes this easy:

Drag and drop files in file explorer
Rename files/folders as needed
Obsidian automatically updates links (if enabled in settings)

Best practice: Make structural changes early in the project when there are fewer documents.

Next Steps

Now that you understand vault organization:

04 - Documentation Workflows - Learn specific workflows for different documentation types

Quick Reference

Folder Numbering System:

00- = Index/Dashboard
10- = Planning
20- = Design
30- = Vendors/External
40- = Meetings (Chronological)
50- = Execution/Build
60- = Post-completion
90- = Reference

File Naming Patterns:

Meetings: YYYY-MM-DD - Type - Subject
Decisions: Decisions - Topic or Decisions Log
Photos: Match image filename
General: Descriptive, proper capitalization

When to Create Subdirectories:

5+ documents in a category
Clear logical grouping
Reduces clutter in parent folder

This structure evolved over 6+ months of active project management. Start simple and grow as needed.

Garage Construction Project

Explorer

Vault Structure and Organization

Vault Structure and Organization

Core Organizational Principles

1. Numeric Prefixes for Ordering

2. Phase-Based Organization

3. Meaningful Names, Not Abbreviations

Garage Project Structure

Folder-by-Folder Breakdown

`00-Index.md` and `index.md`

`10-Planning/` - Planning Phase

`20-Design/` - Design Specifications

`30-Vendors & Contacts/` - External Parties

`40-Meetings/` - Meeting Documentation

`50-Build/` - Construction Phase

`60-After Build/` - Post-Construction

`90-Reference/` - Reference Materials

`pictures/` - Photo Documentation

`Email Imports/` - External Documents

`Templates/` - Document Templates

`CLAUDE.md` - AI Assistant Instructions

File Naming Conventions

General Principles

Specific Patterns

Tag Strategy

Tag Categories

Tag vs. Folder

Scaling Your Structure

Starting Small

Growing Large

Common Pitfalls to Avoid

Migration and Reorganization

Next Steps

Quick Reference

Graph View

Table of Contents

Backlinks

Garage Construction Project

Explorer

Vault Structure and Organization

Vault Structure and Organization

Core Organizational Principles

1. Numeric Prefixes for Ordering

2. Phase-Based Organization

3. Meaningful Names, Not Abbreviations

Garage Project Structure

Folder-by-Folder Breakdown

00-Index.md and index.md

10-Planning/ - Planning Phase

20-Design/ - Design Specifications

30-Vendors & Contacts/ - External Parties

40-Meetings/ - Meeting Documentation

50-Build/ - Construction Phase

60-After Build/ - Post-Construction

90-Reference/ - Reference Materials

pictures/ - Photo Documentation

Email Imports/ - External Documents

Templates/ - Document Templates

CLAUDE.md - AI Assistant Instructions

File Naming Conventions

General Principles

Specific Patterns

Tag Strategy

Tag Categories

Tag vs. Folder

Scaling Your Structure

Starting Small

Growing Large

Common Pitfalls to Avoid

Migration and Reorganization

Next Steps

Quick Reference

Graph View

Table of Contents

Backlinks

`00-Index.md` and `index.md`

`10-Planning/` - Planning Phase

`20-Design/` - Design Specifications

`30-Vendors & Contacts/` - External Parties

`40-Meetings/` - Meeting Documentation

`50-Build/` - Construction Phase

`60-After Build/` - Post-Construction

`90-Reference/` - Reference Materials

`pictures/` - Photo Documentation

`Email Imports/` - External Documents

`Templates/` - Document Templates

`CLAUDE.md` - AI Assistant Instructions