Concepts

The Drydock Metaphor

Like a naval drydock where ships are brought in for major overhauls, Drydock is a workspace for software architecture work:

• Ships = Software projects
• Ocean = Production / upstream repos
• Ship Yard = Where projects are analyzed and decomposed
• Drydock = Your workspace where the real work happens

The Lifecycle

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│    OCEAN                    DRYDOCK                            OCEAN        │
│  (upstream)               (your yard)                       (downstream)    │
│                                                                             │
│  ┌─────────┐     ┌───────────────────────────────────┐     ┌─────────┐     │
│  │ GitHub  │     │                                   │     │  Your   │     │
│  │ GitLab  │ ──▶ │  INTAKE → WORK → RELEASE → SHIP  │ ──▶ │  Prod   │     │
│  │ etc.    │     │                                   │     │ Deploy  │     │
│  └─────────┘     └───────────────────────────────────┘     └─────────┘     │
│                                                                             │
│  Ships arrive    Ships get rebuilt with new parts      Ships return to sea │
│  for overhaul                                          as new vessels      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Phases

1. Intake — Clone/link upstream projects into Ship_Yard/_intake/ (read-only)
2. Analysis — Run analyzers, document architecture in Ship_Yard/_analysis/
3. Extraction — Pull out reusable components into Ship_Yard/_extraction/
4. Assembly — Combine extracted parts into new projects in Projects/
5. Release — Stage for deployment in Release/
6. Ship — Deploy to production, track in Ocean/

Directory Structure

Drydock/
├── StartHere/          # Documentation, guides, templates
├── Ship_Yard/          # Incoming projects for decomposition
│   ├── _intake/        # Raw project clones (READ-ONLY)
│   ├── _analysis/      # Analysis documents
│   └── _extraction/    # Extracted components
├── Tools/              # Utilities for drydock operations
│   ├── mcp_server.py   # MCP server for AI assistants
│   ├── intake/         # Project intake tools
│   ├── analyzers/      # Code analysis tools
│   ├── scaffolders/    # Project scaffolding tools
│   └── builders/       # Build and ship tools
├── Projects/           # New projects being assembled
├── Workbench/          # Experiments and prototypes
├── Release/            # Launch preparation
└── Ocean/              # Deployed fleet registry

Design Principles

• JSON-first — All tools default to JSON for AI consumption, --markdown for humans
• Pure stdlib — Zero external dependencies (except mcp for the MCP server)
• Non-destructive — Analyzers never modify source projects
• Composable — Each tool does one thing; context_compiler orchestrates all
• No fat files — Keep files under 300 lines where possible

Key Analyzer Concepts

Clusters

Groups of files that import each other heavily. High internal connectivity = cohesive component.

Bridge Files

Files that connect multiple clusters. Extract these carefully — they're the glue between components.

Orphans

Files with no import relationships. Easy to extract or remove without breaking anything.

Extraction Risk

• Low — Zero external dependencies. Can be extracted cleanly.
• Medium — A few external deps. Extractable with some interface work.
• High — Many external deps. Extraction requires significant refactoring.