Organizing Technical Blueprints

Directory Structure

blueprints/ ├── README.md # Index and overview ├── {system-name}.md # One file per system ├── {feature-name}.md # One file per feature └── {integration-name}.md # One file per integration

Flat vs Nested

Prefer flat structure for most projects:

• Easier to navigate

• Simpler cross-references

• Less organizational overhead

Use subdirectories only for very large projects:

blueprints/ ├── README.md ├── core/ │ ├── README.md │ └── *.md ├── features/ │ └── *.md └── integrations/ └── *.md

Naming Conventions

File Names

• Use kebab-case: user-authentication.md

• Match system/feature names in code

• Be specific: api-rate-limiting.md not api.md

• Avoid generic names: utils.md , helpers.md

Good Names

• mcp-server.md

• Specific system

• settings-merge.md

• Specific feature

• github-integration.md

• Specific integration

Bad Names

• overview.md

• Too generic (use README.md)

• misc.md

• Catch-all is a smell

• new-feature.md

• Not descriptive

The blueprints/README.md Index

Every blueprints/ directory needs an index:

Technical Blueprints

Implementation documentation for {Project Name}.

Overview

Brief description of what this project does and how blueprints are organized.

Systems

Core systems and their documentation:

Core

• Settings Management - How configuration is loaded and merged
• Plugin System - Plugin discovery and loading

Features

• MCP Server - Model Context Protocol implementation
• Hook Dispatch - How hooks are executed

Integrations

• GitHub Integration - GitHub API integration

Contributing

When adding new blueprints:

1. Check for existing related documentation
2. Use consistent naming and structure
3. Update this index

Avoiding Duplication

The Duplication Problem

Duplicate documentation:

• Gets out of sync

• Confuses readers

• Wastes maintenance effort

Prevention Strategies

Search before creating using native tools

List all existing blueprints

Glob("blueprints/*.md")

Search for blueprints mentioning a topic

Grep("auth", path: "blueprints/", output_mode: "files_with_matches")

Read a specific blueprint to check coverage

Read("blueprints/authentication.md")

One source of truth

• Each concept documented once

• Other locations link to the source

Merge related topics

• Combine tightly coupled systems

• Split only when truly independent

Cross-reference liberally

For authentication details, see User Authentication.

When to Split vs Merge

Keep together when:

• Systems are tightly coupled

• Understanding one requires understanding the other

• They share significant context

Split apart when:

• Systems can be understood independently

• Different audiences need different docs

• File would exceed ~500 lines

Handling Overlap

When systems overlap:

Option 1: Primary Location + References

Document in one place, reference from others:

System A

Authentication

This system uses shared authentication. See Authentication for details.

Option 2: Shared Section

Create a shared blueprint that both reference:

System A

Uses Shared Auth

System B

Uses Shared Auth

Shared Auth

Details here...

Option 3: Inline with Scope

Document the overlap in each, scoped to that system:

System A

Authentication (System A Specific)

How System A specifically uses authentication...

Deprecation

When systems are removed:

• Delete the blueprint file - Don't keep "for history"

• Update the index - Remove from README.md

• Fix broken links - Update any references

• Git history - Use version control for history

Auditing Organization

Periodically check:

• All blueprint files in index?

• All index entries have files?

• No obvious duplicates?

• Names match code terminology?

• Cross-references work?

• No orphaned files?

Tools

Find Orphaned Blueprints

Files not in README.md

for f in blueprints/*.md; do grep -q "$(basename $f)" blueprints/README.md || echo "Orphan: $f" done

Find Duplicate Topics

Similar file names

ls blueprints/*.md | xargs -n1 basename | sort | uniq -d

Similar content

grep -l "specific term" blueprints/*.md