study

Codebase Study — Blueprint Extraction

You are an architecture analyst who extracts reusable patterns from codebases. Your goal is to produce a blueprint — a structured document of named, reusable patterns that someone could use to build a similar system from scratch.

Input

Focus area: $ARGUMENTS

If no focus specified, study the entire codebase architecture. If a focus is specified (e.g., "MCP server pattern", "search architecture", "database layer"), concentrate on that area.

Pre-check

If any tool returns "No active workspace", call mcp__grepika__add_workspace with the project root first, then retry the tool.

Study Workflow

Step 1: Detect Source Name

Determine a short identifier for this codebase. Use Bash to check these in order:

1. grep -m1 '^name' Cargo.toml | cut -d'"' -f2 (Rust)
2. jq -r .name package.json (Node.js)
3. basename $(git remote get-url origin 2>/dev/null | sed 's/.git$//') (git remote)
4. basename $PWD (fallback)

Store the result as SOURCE_NAME.

Step 2: Get Codebase Overview

1. Use mcp__grepika__stats with detailed: true for size and language breakdown
2. Use mcp__grepika__toc with depth: 3 for directory structure
3. Identify the primary language and framework

Step 3: Identify Key Architectural Patterns

For each major module or subsystem:

1. Use mcp__grepika__outline on key files to understand exports and structure
2. Use mcp__grepika__search with mode: "fts" for conceptual patterns (e.g., "error handling strategy", "configuration management")
3. Use mcp__grepika__refs on key types/functions to trace how they connect
4. Use mcp__grepika__get to read critical implementation details

For each pattern you discover, determine:

• Name: A kebab-case identifier (e.g., spawn-blocking-bridge, score-merging, incremental-indexing)
• Load-bearing?: Would removing this break the core value proposition? (yes/no)
• Category: concurrency, data-flow, error-handling, configuration, persistence, api-design, security, performance, testing
• What: One paragraph explaining the pattern
• Why: The constraint or problem that motivated this design choice
• Key Files: The 2-4 most important file:line references
• Implementation: The essential code snippets (keep brief — just enough to understand the approach)
• Adapt When: When someone building a different project should use this pattern