Related Pages

Related topics: CLI and Command Usage, System Architecture

Blueprint Introduction

Blueprint is a local architecture memory system designed to help developers and AI agents understand, navigate, and work effectively with software projects. It generates structured project graphs from source code, enabling faster orientation and more accurate context when making changes.

Overview

Blueprint solves the common problem of diving into unfamiliar or complex codebases by creating a persistent, queryable layer of architectural knowledge. Rather than reading through thousands of files to understand a system, developers can leverage Blueprint's structured output to quickly identify relevant components, dependencies, and architectural patterns.

Core Purpose

The primary goals of Blueprint are:

1. Structured Project Graph Generation - Automatically analyze codebase structure and generate organized representations of files, symbols, imports, and dependencies
2. Architectural Memory Persistence - Store architecture knowledge in a local .blueprint/ directory that can be version-controlled or kept as local developer memory
3. Agent-Friendly Orientation - Provide AI agents with reliable starting points for understanding projects before diving into source code
4. Deterministic Maintenance - Keep architecture documentation synchronized with actual code through automated refresh workflows

Sources: README.md:1-20

Architecture

System Components

Blueprint consists of several integrated components that work together to analyze and document projects:

Sources: README.md:40-60

File Inventory System

The scan engine analyzes the codebase using a categorization system that classifies files into meaningful types:

graph TD
    A[File System] --> B[Scan Engine]
    B --> C{File Type Detection}
    C -->|Source Code| D[parseable]
    C -->|Config| E[config]
    C -->|Documentation| F[documentation]
    C -->|Test| G[test]
    C -->|Asset| H[asset]
    C -->|Lockfile| I[lockfile]
    C -->|Script| J[script]

The categorization logic uses path segment analysis and file extension matching:

// From src/tools/scan/scan-file-inventory-builder.ts
if (segments.includes("test") || segments.includes("tests")) {
  return "test";
}
if (base.endsWith(".md") || language === "markdown") {
  return "documentation";
}
if (segments.includes("assets") || ["html", "css", "svg"].includes(language)) {
  return "asset";
}

Sources: src/tools/scan/scan-file-inventory-builder.ts:1-50

Code Analysis Engine

The analysis engine performs deep parsing on supported languages to extract symbols, imports, and exports:

// From src/tools/scan/scan-code-analysis-engine.ts
interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: Record<string, FileFacts>;
  symbols: Record<string, SymbolFacts>;
  imports: Import[];
  exports: Export[];
  dependencies: Dependency[];
  parseErrors: ParseError[];
}

The engine tracks validation state to ensure complete analysis:

interface Validation {
  isComplete: boolean;
  inventoryFiles: number;
  parseableFiles: number;
  parsedFiles: number;
  parseErrors: number;
  unaccountedFiles: string[];
}

Sources: src/tools/scan/scan-code-analysis-engine.ts:1-80

Project Memory Structure

Blueprint stores architecture memory in a .blueprint/ directory with the following structure:

Generated Artifacts

Sources: README.md:25-35

Group Documentation Template

Each group document follows a consistent structure:

• Snapshot - Quick orientation and high-level description
• Responsibilities - Ownership boundaries and out-of-scope areas
• Core Flow - Runtime behavior and data flow explanation
• Contracts & Invariants - Behavior that must not be broken
• Key Files - Main source files for the group
• Change Guide - Files or contracts that should change together
• Pitfalls - Known risks and common mistakes
• Tests - Most relevant verification points
• Debugging - Failure-mode hints
• Extension / Open Questions - Uncertainty and known gaps

Sources: AGENTS.md:40-65

Workflows

Initial Setup Workflow

graph LR
    A[blueprint scan] --> B[blueprint group mode: prepare]
    B --> C[Create grouping plan]
    C --> D[blueprint group mode: apply]
    D --> E[blueprint compose]
    E --> F[.blueprint/ memory created]
    F --> G[AGENTS.md patched]

To initialize Blueprint for a project:

1. Run blueprint.scan to build file inventory and code analysis
2. Run blueprint.group with mode: "prepare" to analyze grouping options
3. Create a compact grouping plan from the prepare output
4. Run blueprint.group with mode: "apply" to apply the grouping
5. Run blueprint.compose to write the final Blueprint output

Sources: README.md:55-75

Maintenance Workflow

When project changes add, move, delete, or substantially change files:

graph TD
    A[Code Changes] --> B[Run blueprint.refresh]
    B --> C{New files unassigned?}
    C -->|Yes| D[Run blueprint.group.update]
    C -->|No| E[Update affected group docs]
    D --> E
    E --> F[Architecture docs synchronized]

Sources: README.md:75-85

Blueprint Viewer

Blueprint includes a lightweight React/Vite viewer for visualizing project architecture.

Viewing Generated Blueprint

To view a generated Blueprint:

blueprint open

This command:

1. Reads .blueprint/blueprint-output.json and .blueprint/groups/*.md
2. Writes a self-contained .blueprint/index.html
3. Opens it in the default browser

Static Viewer Features

The viewer generates self-contained HTML with:

• Inline JavaScript
• Inline CSS
• Securely embedded JSON data

graph TD
    A[Blueprint Data] --> B[XSS/Content Escape]
    B --> C[<script type="application/json">]
    C --> D[Inline CSS/JS]
    D --> E[Self-contained HTML]

Data is embedded using <script id="blueprint-data" type="application/json"> rather than window.__BLUEPRINT_DATA__ for better security isolation.

Sources: README.md:90-105

MCP Integration

Blueprint provides Model Context Protocol integration for AI agent workflows:

Agent Instructions Snippet

The system automatically patches AGENTS.md with Blueprint-specific instructions:

// From src/lib/agent-instructions.ts
export function renderBlueprintAgentsSnippet(): string {
  return [
    beginMarker,
    "## Blueprint MCP",
    "",
    "This project uses Blueprint MCP for local architecture memory.",
    "",
    "Before broad codebase exploration, read:",
    "",
    "`node_modules/blueprint-mcp-server/docs/agents.md`",
    "",
    "If Blueprint memory exists, start with:",
    "",
    "`.blueprint/brief.md`",
    "",
    endMarker,
  ].join("\n");
}

Sources: src/lib/agent-instructions.ts:1-30

Agent Workflow Guidelines

When working with Blueprint-enabled projects, agents should:

1. Read .blueprint/brief.md for the project map
2. Identify the group or groups that may be relevant
3. Search Blueprint Markdown docs with task-specific keywords
4. Read only the smallest useful set of group documents
5. Inspect source code only where docs are insufficient

Sources: AGENTS.md:1-25

Language Support

Blueprint uses Tree-sitter analysis for deep symbol/import extraction:

Sources: README.md:125-135

Source of Truth Principles

Blueprint memory is an orientation layer, not the authority:

Source code is the ground truth.

If Blueprint docs conflict with source code, trust the source code. After changing source behavior, update the relevant Blueprint group doc if the memory became stale.

Sources: AGENTS.md:75-85

Development

Building and Testing

npm install
npm run build
npm run lint
npm test

Working Rules

When making changes to Blueprint-enabled projects:

• Keep changes scoped to the user's task
• Prefer existing project patterns over new abstractions
• Add or update tests when behavior changes
• Run the smallest relevant verification first
• Do not edit generated files unless explicitly required
• Do not modify secrets, local environment files, or unrelated configuration

Sources: AGENTS.md:90-100

Key Tools Reference

Sources: README.md:85-95

Related Pages

Related topics: Blueprint Introduction, MCP Server Implementation

CLI and Command Usage

Blueprint provides a command-line interface (CLI) for scanning code repositories, organizing files into semantic groups, and generating project documentation. The CLI is designed to work with MCP (Model Context Protocol) clients and supports a self-contained static viewer without requiring an HTTP server.

Overview

The Blueprint CLI operates as a terminal-based tool that generates a structured project graph from source code. It focuses on code comprehension rather than modification, providing developers with an orientation layer that points to relevant source files without altering the project itself.

Blueprint's command suite handles the complete lifecycle from initial repository analysis to documentation generation:

Sources: README.md:30-36

Core Commands

blueprint scan

The scan command performs initial repository analysis by building a file inventory and extracting code analysis artifacts. This command identifies all files in the project and categorizes them based on type, language, and path patterns.

blueprint scan

The scan process determines file categories using pattern matching:

Sources: src/tools/scan/scan-file-inventory-builder.ts:20-65

The scan command produces several artifacts stored in the .blueprint/ directory:

Sources: README.md:49-53

blueprint group

The group command manages semantic file organization. It operates in two modes:

# Prepare mode: generates grouping suggestions
blueprint group --mode prepare

# Apply mode: commits the grouping plan
blueprint group --mode apply --plan <grouping-configuration>

#### Prepare Mode

In prepare mode, the tool analyzes the file inventory and generates a suggested grouping plan based on code relationships, shared dependencies, and functional areas. The output helps developers understand how files could be semantically organized without automatically applying changes.

#### Apply Mode

In apply mode, the tool takes a user-defined or tool-generated grouping plan and reorganizes the Blueprint's understanding of the codebase. The plan specifies which files belong to which groups and assigns roles (e.g., core, support, test) to files within each group.

Sources: README.md:30-36

blueprint compose

The compose command generates the final Blueprint documentation by combining scan results, grouping information, and any custom documentation:

blueprint compose

This command writes output to the .blueprint/ directory and patches AGENTS.md with a marker-delimited Blueprint snippet. The snippet provides project-specific guidance for AI agents without overwriting existing project instructions.

Sources: README.md:38-43

blueprint refresh

The refresh command updates Blueprint state when the filesystem changes:

blueprint refresh

This command compares the current filesystem against the stored snapshot and updates the project graph accordingly. It handles:

• New files added to the project
• Deleted files removed from the project
• Modified files with updated analysis
• Renamed or moved files

Sources: README.md:30-36

blueprint group update

After a refresh operation, unassigned files may exist. This command manages those files:

blueprint group update

The update operation can:

• Assign new files to existing groups based on patterns
• Create new groups for files that don't match existing patterns
• Remove empty groups that no longer have assigned files

Sources: README.md:30-36

blueprint open

The open command launches the Blueprint viewer:

# Single open
blueprint open

# Watch mode - auto-regenerate on changes
blueprint open --watch

The viewer reads from .blueprint/blueprint-output.json and .blueprint/groups/*.md, then generates a self-contained .blueprint/index.html file that opens in the default browser.

Important characteristics:

• Does not start an HTTP server
• Does not include chat, LLM execution, or HTTP APIs
• Watch mode regenerates HTML when source files change but does not inject live reload code

Sources: README.md:56-68

Initial Workflow

For first-time setup, run the following MCP tool sequence:

1. blueprint.scan           # Inventory all files and analyze code
2. blueprint.group          # With mode: "prepare"
3. [Create grouping plan]   # Developer creates compact grouping
4. blueprint.group          # With mode: "apply"
5. blueprint.compose        # Generate final documentation

Sources: README.md:58-65

graph TD
    A[Start] --> B[blueprint scan]
    B --> C[blueprint group prepare]
    C --> D[Developer Reviews Suggestions]
    D --> E[Developer Creates Plan]
    E --> F[blueprint group apply]
    F --> G[blueprint compose]
    G --> H[Blueprint Memory Ready]
    
    H --> I[blueprint open]
    I --> J[.blueprint/index.html Generated]

Maintenance Workflow

When project changes occur (new files, deletions, or architectural changes):

1. blueprint.refresh           # Update Blueprint state
2. blueprint.group.update      # Handle unassigned files
3. [Update affected group docs] # Modify .blueprint/groups/*.md

Sources: README.md:67-73

Viewer Command Architecture

The viewer generation follows a specific architecture that produces self-contained HTML:

graph LR
    A[blueprint open] --> B[Read blueprint-output.json]
    A --> C[Read .blueprint/groups/*.md]
    B --> D[Generate index.html]
    C --> D
    D --> E[Inline CSS]
    D --> F[Inline JS]
    D --> G[Embed JSON Data]
    E --> H[Self-contained HTML]
    F --> H
    G --> H
    H --> I[Browser Render]

The embedded data uses <script id="blueprint-data" type="application/json"> for secure JSON embedding, protecting against XSS and </script> closing tag injection risks.

Sources: todos_120526.md:12-15

Agent Integration

Blueprint CLI integrates with AI agents through AGENTS.md files that contain marker-based patches. The system uses stable section headings for navigation:

• Core Flow
• Contracts & Invariants
• Change Guide
• Pitfalls
• Tests

Sources: AGENTS.md:4-10

Agent Budget Guidelines

When working with Blueprint in agentic contexts:

Sources: AGENTS.md:1-7

Development Commands

For developers working on Blueprint itself:

npm install      # Install dependencies
npm run build    # Build the project
npm run lint     # Run linter
npm test         # Run tests

Sources: README.md:75-80

Command Output Structure

Blueprint generates structured output files in the .blueprint/ directory:

Sources: README.md:49-53

Language Support

The CLI uses Tree-sitter for deep code analysis of supported languages:

Sources: README.md:81-88

Configuration Notes

• .blueprint/ is local generated memory by default
• Teams decide whether to commit to version control or add to .gitignore
• Source code remains the single source of truth
• Do not edit blueprint-output.json manually

Sources: README.md:53-56

Error Handling

When commands encounter issues:

Sources: src/tools/scan/scan-code-analysis-engine.ts:15-22

Summary

The Blueprint CLI provides a comprehensive toolkit for code comprehension and documentation:

1. Scan creates a complete inventory of project files
2. Group organizes files into semantic clusters
3. Compose generates documentation and updates agent guidance
4. Refresh keeps the documentation synchronized with filesystem changes
5. Open provides a self-contained HTML viewer

All operations are designed to enhance developer understanding without modifying source code or requiring a persistent HTTP server.

Related Pages

Related topics: Scan Tool, Group Tool, Compose Tool, Refresh Tool

System Architecture

Overview

Blueprint is a documentation and code organization system that generates a structured "memory" layer for software projects. Rather than modifying source code, it creates an orientation layer stored in the .blueprint/ directory, enabling AI agents and developers to understand project structure without reading every file.

Sources: README.md

The system operates as a transport-agnostic architecture that can function in two modes:

1. Static mode: Embeds data directly into index.html for self-contained viewing
2. HTTP mode: Serves data via API for interactive development environments

Sources: todos_120526.md

Core Components

Blueprint's architecture consists of four primary tool layers, each responsible for a distinct phase of the documentation lifecycle.

Tool Layer Architecture

graph TD
    A[blueprint scan] --> B[blueprint group]
    B --> C[blueprint compose]
    C --> D[blueprint refresh]
    
    A1[File Inventory] --> B1[Grouping Assignment]
    B1 --> C1[Memory Output]
    C1 --> D1[State Refresh]
    
    A2[Code Analysis] --> B2[Pattern Validation]
    B2 --> C2[Markdown Notes]
    C2 --> D2[Incremental Updates]

Component Responsibilities

Sources: README.md

File Inventory System

The scanning engine builds a comprehensive file inventory by categorizing each file in the project.

File Categorization Logic

Files are classified into categories based on path segments, file extensions, and naming patterns:

graph LR
    A[File Path] --> B{Extension Check}
    B -->|spec.ts / test.ts| C[test]
    B -->|package-lock.json| D[lockfile]
    B -->|package.json / .config.ts| E[config]
    B -->|readme.md / *.md| F[documentation]
    B -->|.sh / scripts/| G[script]
    B -->|.svg / css / assets/| H[asset]

Sources: src/tools/scan/scan-file-inventory-builder.ts

Category Detection Rules

Sources: src/tools/scan/scan-file-inventory-builder.ts

Code Analysis Engine

The analysis engine parses all "parseable" files to extract structural information.

Analysis Facts Model

interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: Record<string, FileFacts>;
  symbols: Record<string, SymbolFacts>;
  imports: ImportStatement[];
  exports: ExportStatement[];
  dependencies: Dependency[];
  unresolvedImports: UnresolvedImport[];
  parseErrors: ParseError[];
  summary: AnalysisSummary;
  validation: ValidationStatus;
}

Sources: src/tools/scan/scan-code-analysis-engine.ts

Summary Tracking

The engine maintains aggregate statistics during parsing:

Sources: src/tools/scan/scan-code-analysis-engine.ts

Group Assignment System

Files are assigned to semantic groups using glob-based pattern matching.

Pattern Matching Engine

The grouper supports wildcard patterns for matching file paths:

graph TD
    A[Pattern] --> B{Character}
    B -->|glob `*`| C[Match any chars except /]
    B -->|glob `?`| D[Match single char except /]
    B -->|literal| E[Exact match required]
    C --> F[Build Regex]
    D --> F
    E --> F
    F --> G[^pattern$]

Sources: src/tools/group/grouping-assignment-engine.ts

Grouped File Structure

interface GroupedFile {
  fileId: string;
  path: string;
  category: string;
  language: string;
  importance: "critical" | "important" | "standard" | "unknown";
  role: string;
}

Sources: src/tools/group/grouping-assignment-engine.ts

Validation and Suggestions

When patterns fail to match any files, the system provides diagnostic information:

interface UnknownPattern {
  pattern: string;
  reason: string;
  suggestions: string[];
}

The suggester extracts suffixes from patterns and finds similar paths in the inventory.

Sources: src/tools/group/grouping-assignment-engine.ts

Group Documentation Template

Each group follows a canonical documentation structure that agents can navigate using stable headings.

Section Structure

graph LR
    A[Snapshot] --> B[Responsibilities]
    B --> C[Core Flow]
    C --> D[Contracts & Invariants]
    D --> E[Key Files]
    E --> F[Change Guide]
    F --> G[Pitfalls]
    G --> H[Tests]

Sources: AGENTS.md

Sources: AGENTS.md

Frontend Component Architecture

The Blueprint frontend is a React-based application with a tabbed interface.

Application Structure

graph TD
    A[BlueprintApp] --> B[Tab Bar]
    A --> C[Main Content Area]
    
    B --> D[Canvas Tab]
    B --> E[Group Detail Tabs]
    
    C --> D
    C --> E
    
    E --> F[GroupDetailPanel]
    F --> G[Overview]
    F --> H[Files]
    F --> I[Connections]
    F --> J[Architecture]
    F --> K[Guide]

Sources: frontend/src/components/BlueprintApp.tsx Sources: frontend/src/components/blueprint/GroupDetailPanel.tsx

Sub-Tab Content Mapping

Sources: frontend/src/components/blueprint/GroupDetailPanel.tsx

SectionCard Component

The SectionCard component provides collapsible content sections with accent colors:

interface SectionCardProps {
  title: string;
  content: string;
  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc';
  defaultOpen?: boolean;
  index?: number;
}

Sources: frontend/src/components/blueprint/GroupDetailPanel.tsx

Static Viewer Rendering

The HTML renderer creates self-contained viewer files by inlining assets.

Inlining Process

graph LR
    A[Template HTML] --> B[Inline CSS]
    B --> C[Inline JS]
    C --> D[Embed JSON Data]
    D --> E[Escape & Validate]
    E --> F[index.html]

Sources: src/viewer/render-html.ts

Asset Inlining Strategy

The renderer processes three asset types:

Sources: src/viewer/render-html.ts

Data Embedding Security

JSON data is embedded using <script type="application/json"> to avoid XSS risks:

<script id="blueprint-data" type="application/json">
  <!-- Safely escaped JSON here -->
</script>

Sources: todos_120526.md

Workflow State Machine

Initial Workflow

graph TD
    A[Start] --> B[blueprint scan]
    B --> C[blueprint group prepare]
    C --> D{Create grouping plan}
    D --> E[blueprint group apply]
    E --> F[blueprint compose]
    F --> G[Complete]
    
    H[hydrate group docs] -.-> G

Maintenance Workflow

graph TD
    A[Project Change] --> B[blueprint refresh]
    B --> C{New unassigned files?}
    C -->|Yes| D[blueprint group update]
    C -->|No| E[Update affected group docs]
    D --> E
    E --> F[Complete]

Sources: README.md

Artifact Storage

The system uses typed artifact storage for persisting scan results, groupings, and composed output.

Artifact Types

Sources: src/lib/artifact-store.ts

Validation Status

Each analysis maintains a validation record:

interface ValidationStatus {
  isComplete: boolean;
  inventoryFiles: number;
  parseableFiles: number;
  parsedFiles: number;
  metadataOnlyFiles: number;
  skippedMetadataOnlyFiles: number;
  parseErrors: number;
  unaccountedFiles: string[];
}

Sources: src/tools/scan/scan-code-analysis-engine.ts

Key Design Principles

1. Source of Truth: Source code remains the source of truth; .blueprint/ is generated memory only
2. Local by Default: Blueprint memory is stored in .blueprint/ (not in node_modules)
3. Transport Agnostic: Supports both static HTML and HTTP API modes
4. Safe Embedding: JSON data is safely escaped before HTML embedding
5. Canonical Structure: Group docs follow a stable template for consistent navigation

Sources: README.md Sources: todos_120526.md

Related Pages

Related topics: System Architecture, Task Context Tool

MCP Server Implementation

The Blueprint MCP Server provides a Model Context Protocol interface for AI agents to interact with codebase architecture memory. It exposes tools for scanning codebases, grouping files semantically, composing documentation, and maintaining architectural state across project changes.

Overview

Blueprint operates as a local architecture memory layer that sits above source code. The MCP Server acts as the bridge between AI agents and the Blueprint tooling, enabling deterministic project understanding without manual documentation overhead.

graph TD
    A[AI Agent] -->|MCP Protocol| B[Blueprint MCP Server]
    B -->|blueprint.scan| C[File Inventory Builder]
    B -->|blueprint.group| D[Semantic Grouper]
    B -->|blueprint.compose| E[Documentation Writer]
    B -->|blueprint.refresh| F[State Refresher]
    C -->|Artifacts| G[blueprint-output.json]
    D -->|Groupings| H[groups/*.md]
    E -->|Memory| G & H
    F -->|Sync| G & H

Sources: README.md:1-15

MCP Tools Architecture

Available Tools

Sources: README.md:30-36

Tool Workflow

graph LR
    A[Initial Setup] --> B[scan]
    B --> C[group prepare]
    C --> D[Review Plan]
    D --> E[group apply]
    E --> F[compose]
    F --> G[Memory Written]
    
    H[Maintenance] --> I[refresh]
    I --> J{Unassigned Files?}
    J -->|Yes| K[group.update]
    J -->|No| L[Update Docs Only]
    K --> M[Update group/*.md]

#### Initial Workflow

1. blueprint.scan - Builds file inventory and code analysis artifacts
2. blueprint.group with mode: "prepare" - Prepares grouping plan
3. Review the compact grouping plan output
4. blueprint.group with mode: "apply" - Applies the grouping
5. blueprint.compose - Writes .blueprint/ memory and patches AGENTS.md

Sources: README.md:18-27

#### Maintenance Workflow

1. Run blueprint.refresh when project changes occur
2. If new files are unassigned, run blueprint.group.update
3. Update only affected .blueprint/groups/*.md notes when architecture changes

Sources: README.md:29-33

Scan Tool Implementation

File Inventory Builder

The scan-file-inventory-builder.ts handles filesystem traversal and file classification. It categorizes files into types based on naming conventions and path segments.

#### File Type Classification

Sources: src/tools/scan/scan-file-inventory-builder.ts:1-80

Code Analysis Engine

The scan-code-analysis-engine.ts performs deep analysis on parseable files, extracting symbols, imports, exports, and dependencies.

#### Analysis Facts Model

interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: Record<string, FileAnalysis>;
  symbols: Record<string, Symbol[]>;
  imports: ImportStatement[];
  exports: ExportStatement[];
  dependencies: Dependency[];
  unresolvedImports: UnresolvedImport[];
  parseErrors: ParseError[];
  summary: {
    totalFiles: number;
    parseableFiles: number;
    metadataOnlyFiles: number;
    plannedFiles: number;
    parsedFiles: number;
    symbols: number;
    imports: number;
    exports: number;
    dependencies: number;
    parseErrors: number;
  };
  validation: AnalysisValidation;
}

Sources: src/tools/scan/scan-code-analysis-engine.ts:20-40

#### Language Support

Blueprint uses Tree-sitter analysis for:

Sources: README.md:60-65

Validation Model

interface AnalysisValidation {
  isComplete: boolean;
  inventoryFiles: number;
  parseableFiles: number;
  parsedFiles: number;
  metadataOnlyFiles: number;
  skippedMetadataOnlyFiles: number;
  parseErrors: number;
  unaccountedFiles: string[];
}

Sources: src/tools/scan/scan-code-analysis-engine.ts:42-50

Agent Integration

AGENTS.md Integration

The MCP Server integrates with project AGENTS.md files using marker-delimited snippets. When blueprint.compose runs, it patches the AGENTS.md without overwriting existing project instructions.

#### Snippet Format

<!-- BEGIN:blueprint-mcp-agent-rules -->

## Blueprint MCP

This project uses Blueprint MCP for local architecture memory.

Before broad codebase exploration, read:

`node_modules/blueprint-mcp-server/docs/agents.md`

If Blueprint memory exists, start with:

`.blueprint/brief.md`

<!-- END:blueprint-mcp-agent-rules -->

Sources: src/lib/agent-instructions.ts:15-30

Agent Instruction Rendering

export function renderBlueprintAgentsSnippet(): string {
  return [
    beginMarker,
    "",
    "## Blueprint MCP",
    "",
    "This project uses Blueprint MCP for local architecture memory.",
    "",
    "Before broad codebase exploration, read:",
    "",
    "`node_modules/blueprint-mcp-server/docs/agents.md`",
    "",
    "If Blueprint memory exists, start with:",
    "",
    "`.blueprint/brief.md`",
    "",
    endMarker,
  ].join("\n");
}

Sources: src/lib/agent-instructions.ts:40-58

Blueprint Memory Structure

graph TD
    subgraph ".blueprint/"
        A[blueprint-output.json] -->|Deterministic| B[Group definitions]
        A -->|Deterministic| C[File inventory]
        A -->|Deterministic| D[Analysis facts]
        E[brief.md] -->|Overview| F[Architectural groups]
        G[groups/*.md] -->|Detailed| H[Responsibilities]
        G -->|Detailed| I[Core Flow]
        G -->|Detailed| J[Contracts & Invariants]
        G -->|Detailed| K[Change Guide]
        G -->|Detailed| L[Pitfalls]
    end
    
    M[refresh-scan.json] -->|Hash snapshot| N[Deterministic refresh]

Generated Artifacts

Sources: README.md:9-12

Group Documentation Template

Files under .blueprint/groups/*.md follow a stable template:

Sources: AGENTS.md:1-35

Viewer Integration

Blueprint ships a lightweight React/Vite viewer that reads generated Blueprint data.

Static HTML Generation

graph LR
    A[blueprint open] --> B[Read JSON & MD]
    B --> C[Generate index.html]
    C --> D[Open in browser]
    
    E[--watch mode] --> F[Regenerate on changes]

#### Viewer Features

• Self-contained HTML with inline JS and CSS
• Secure embedded JSON data
• No HTTP server required
• No chat or LLM execution

Sources: README.md:38-50

Import Resolution System

Candidate Import Path Resolution

The code analysis engine resolves relative imports by checking multiple candidate paths:

private candidateImportPaths(basePath: string): string[] {
  const candidates = [basePath];
  
  if (ext) {
    return candidates;
  }
  
  return [
    basePath,
    `${basePath}.ts`,
    `${basePath}.tsx`,
    `${basePath}.js`,
    `${basePath}.jsx`,
    `${basePath}/index.ts`,
    `${basePath}/index.tsx`,
    `${basePath}/index.js`,
    `${basePath}/index.jsx`,
  ];
}

Sources: src/tools/scan/scan-code-analysis-engine.ts:80-95

Key Design Principles

Source of Truth

Sources: AGENTS.md:55-60

Working Rules

1. Keep changes scoped to the user's task
2. Prefer existing project patterns over new abstractions
3. Add or update tests when behavior changes
4. Run the smallest relevant verification first
5. Do not edit generated files unless explicitly required

Sources: AGENTS.md:65-70

Related Pages

Related topics: System Architecture, Group Tool

Scan Tool

The Scan Tool (blueprint.scan) is the first stage in the Blueprint workflow. It performs filesystem traversal and static code analysis to build a comprehensive File Inventory and Analysis Facts artifact. These artifacts serve as the foundational data layer for subsequent grouping, composition, and visualization operations.

Overview

The Scan Tool operates in two distinct phases:

1. File Inventory Phase - Traverses the project filesystem, categorizes files by role (source, test, config, etc.), and detects the technology stack
2. Code Analysis Phase - Parses source files using Tree-sitter to extract symbols, imports, exports, and dependency relationships

┌─────────────────┐    ┌──────────────────────────┐    ┌─────────────────┐
│  Filesystem     │───▶│  FileInventoryBuilder    │───▶│  FileInventory  │
│  Traversal      │    │  (scan-file-inventory)   │    │  Artifact       │
└─────────────────┘    └──────────────────────────┘    └────────┬────────┘
                                                                  │
                                                                  ▼
┌─────────────────┐    ┌──────────────────────────┐    ┌─────────────────┐
│  AnalysisFacts  │◀───│  CodeAnalysisEngine      │◀───│  Parseable      │
│  Artifact       │    │  (scan-code-analysis)    │    │  Files          │
└─────────────────┘    └──────────────────────────┘    └─────────────────┘

Architecture

Core Components

Class: ScanFileInventoryBuilder

The ScanFileInventoryBuilder class is responsible for walking the project directory and building a structured file inventory.

class ScanFileInventoryBuilder {
  // Builds the complete file inventory from a root path
  async build(rootPath: string): Promise<FileInventory>
  
  // Validates inventory completeness against scanned paths
  private validateInventory(scannedPaths: string[], files: InventoryFile[]): FileInventoryValidation
}

资料来源：scan-file-inventory-builder.ts:1-50

Class: CodeAnalysisEngine

The CodeAnalysisEngine class consumes the file inventory and performs deep static analysis on parseable files.

class CodeAnalysisEngine {
  async handle(args: CodeAnalysisEngineArgs, store: ArtifactStore): Promise<ToolResult>
  
  // Builds a mapping from file paths to file IDs for efficient lookup
  private buildPathToFileId(inventory: FileInventory): Map<string, string>
  
  // Computes validation metrics for the analysis results
  private computeValidation(parsedFileIds, parseErrorFileIds, inventory): AnalysisValidation
}

资料来源：scan-code-analysis-engine.ts:1-60

File Inventory Phase

File Role Detection

The scanner categorizes each file into one of the following roles based on its path and extension:

资料来源：scan-file-inventory-builder.ts:50-130

Analysis Level Classification

Each file receives an analysisLevel designation:

资料来源：scan-code-analysis-engine.ts:20-30

Stack Detection

The builder detects the technology stack from two sources:

1. Language counts - Extracted from file extensions
2. Path patterns - Special directories indicate additional technologies

资料来源：scan-file-inventory-builder.ts:180-200

Package Manager Detection

Detects which package managers are in use:

资料来源：scan-file-inventory-builder.ts:150-175

Code Analysis Phase

Tree-sitter Integration

The analysis engine uses Tree-sitter for parsing supported languages:

Note: Files in other languages are still included in the inventory but receive metadata-only analysis.

资料来源：README.md - Language Support section

Extracted Facts

For each parseable file, the engine extracts:

interface AnalysisFacts {
  inventoryArtifactId: string;
  rootPath: string;
  files: Record<string, ParsedFile>;      // fileId -> parsed content
  symbols: Record<string, Symbol[]>;       // fileId -> extracted symbols
  imports: ImportStatement[];              // all import statements
  exports: ExportStatement[];              // all export statements
  dependencies: DependencyEdge[];         // inter-file dependencies
  unresolvedImports: UnresolvedImport[];   // imports without matching exports
  parseErrors: ParseError[];               // parsing failures
  summary: AnalysisSummary;
  validation: AnalysisValidation;
}

资料来源：scan-code-analysis-engine.ts:30-60

Validation Model

The analysis produces a validation object tracking completeness:

interface AnalysisValidation {
  isComplete: boolean;                    // true if all files processed
  inventoryFiles: number;                 // total files in inventory
  parseableFiles: number;                // files marked as parseable
  parsedFiles: number;                   // successfully parsed count
  metadataOnlyFiles: number;             // metadata-only file count
  skippedMetadataOnlyFiles: number;      // metadata-only files skipped
  parseErrors: number;                   // parse failure count
  unaccountedFiles: string[];            // files not in parsed or error sets
}

资料来源：scan-code-analysis-engine.ts:60-75

Data Flow

graph TD
    A[Root Path] --> B[ScanFileInventoryBuilder.build]
    B --> C[Filesystem Walk]
    C --> D[File Categorization]
    D --> E[Stack Detection]
    E --> F[FileInventory Artifact]
    
    F --> G[CodeAnalysisEngine.handle]
    G --> H[Filter Parseable Files]
    H --> I[For Each Parseable File]
    I --> J[Read File Content]
    J --> K[Create Tree-sitter Parser]
    K --> L[Extract Symbols]
    K --> M[Extract Imports]
    K --> N[Extract Exports]
    L --> O[Build Dependency Graph]
    M --> O
    N --> O
    O --> P[AnalysisFacts Artifact]
    
    I --> Q[Handle Parse Errors]
    Q --> P

Output Artifacts

FileInventory Artifact

AnalysisFacts Artifact

Configuration & Behavior

Summary Statistics

The FileInventory summary provides project metrics:

interface InventorySummary {
  totalFiles: number;
  parseableFiles: number;
  metadataOnlyFiles: number;
  byLanguage: Record<string, number>;
  byRole: Record<string, number>;
}

资料来源：scan-file-inventory-builder.ts:200-220

Validation Completeness Check

The engine computes isComplete as:

isComplete = (parsedFiles + parseErrorFiles + skippedMetadataOnlyFiles) === totalInventoryFiles

If isComplete is false, there are files in the inventory that were neither successfully parsed nor accounted for in error/skipped sets.

资料来源：scan-code-analysis-engine.ts:100-115

Integration with Blueprint Workflow

The Scan Tool is the entry point for the Blueprint system:

blueprint.scan → blueprint.group → blueprint.compose

1. blueprint.scan - Produces fileInventory and analysisFacts artifacts
2. blueprint.group - Consumes these artifacts to create semantic groupings
3. blueprint.compose - Generates the final blueprint-output.json

资料来源：README.md - Initial Workflow section

Error Handling

The Scan Tool handles several error conditions:

资料来源：scan-code-analysis-engine.ts:80-95

Refresh Maintenance

When the filesystem changes:

blueprint.refresh

This re-runs the scan to update the file inventory and analysis facts, ensuring the Blueprint state reflects the current project structure.

资料来源：README.md - Maintenance Workflow section

Related Pages

Related topics: System Architecture, Scan Tool, Compose Tool

Group Tool

Overview

The Group Tool is a core component of the Blueprint system responsible for organizing source files into semantic architectural groups. It bridges the gap between raw file inventory (produced by the Scan Tool) and the structured architectural documentation (produced by the Compose Tool).

Purpose: The Group Tool transforms a flat list of files into a meaningful hierarchical structure where files are assigned to architectural groups based on semantic patterns, role assignments, and cross-group relationships.

Scope:

• Processes file inventory data from the Scan Tool
• Assigns files to groups based on glob patterns and semantic rules
• Validates grouping plans for completeness and conflicts
• Aggregates cross-group edges and relationships
• Handles fallback grouping for unassigned files
• Supports both prepare and apply modes for iterative group planning

Sources: src/tools/group/grouping-assignment-engine.ts:1-50

Architecture

Component Flow

graph TD
    A[FileInventory] --> B[GroupingAssignmentEngine]
    B --> C[GroupingPlanValidator]
    C --> D[GroupingResult]
    D --> E[ComposeOutputBuilder]
    E --> F[BlueprintOutput]
    
    G[GroupingPlan] --> B
    H[FileFacts] --> B

Core Components

Sources: src/tools/group/grouping-assignment-engine.ts:1-30

Data Models

Key Types

// GroupedFile represents a file assigned to a group
interface GroupedFile {
  fileId: string;
  path: string;
  category: string;
  language: string;
  importance: "unknown";
  role: "unknown";
}

// BlueprintGroup represents a semantic architectural group
interface BlueprintGroup {
  id: string;
  name: string;
  description: string;
  kind: string;
  confidence: number;
  files: GroupedFile[];
}

// GroupingResult contains the complete grouping output
interface GroupingResult {
  groups: BlueprintGroup[];
  crossGroupEdges: CrossGroupEdge[];
}

Sources: src/tools/group/grouping.types.ts

Group Assignment Strategy

The assignment engine uses a multi-stage process:

1. Pattern Matching: Files are matched against glob-like patterns specified in the grouping plan
2. Role Assignment: Each file receives a role based on pattern matching and heuristics
3. Fallback Grouping: Unmatched files are placed in a fallback group
4. Edge Aggregation: Cross-group relationships are aggregated from file-level dependencies

Sources: src/tools/group/grouping-assignment-engine.ts:50-150

Pattern Matching Engine

Regex-Based Pattern System

The assignment engine converts user-friendly glob patterns into regular expressions for flexible file matching:

graph LR
    A[Glob Pattern] --> B[buildRegex]
    B --> C[Regular Expression]
    C --> D[File Path Matching]
    D --> E{Match?}
    E -->|Yes| F[Assign to Group]
    E -->|No| G[Next Pattern]

Supported Pattern Syntax

Sources: src/tools/group/grouping-assignment-engine.ts:100-130

Pattern Processing Method

private buildRegex(pattern: string): RegExp {
  let source = "";
  for (const char of pattern) {
    if (char === "*") {
      source += "[^/]*";
      continue;
    }
    if (char === "?") {
      source += "[^/]";
      continue;
    }
    source += this.escapeRegex(char);
  }
  return new RegExp(`^${source}$`);
}

Sources: src/tools/group/grouping-assignment-engine.ts:115-127

Grouping Workflow

Prepare Mode

In prepare mode, the tool analyzes the file inventory and suggests:

• Suggested group structures based on directory structure and file patterns
• Suggested role assignments for files
• Cross-group relationship candidates
• Confidence scores for each suggestion

sequenceDiagram
    participant User
    participant GroupTool
    participant ScanTool
    participant ComposeTool
    
    User->>ScanTool: blueprint.scan
    ScanTool->>GroupTool: FileInventory
    GroupTool->>GroupTool: Analyze patterns
    GroupTool-->>User: Suggested grouping plan
    User->>GroupTool: Refine grouping plan
    User->>GroupTool: blueprint.group(mode: apply)
    GroupTool->>ComposeTool: GroupingResult
    ComposeTool-->>User: Blueprint output

Apply Mode

In apply mode, the tool:

1. Validates the provided grouping plan
2. Assigns files to groups based on patterns
3. Aggregates cross-group edges
4. Returns the structured GroupingResult

Sources: src/tools/group/index.ts

Validation System

Plan Validation Checks

The GroupingPlanValidator performs comprehensive validation:

Sources: src/tools/group/grouping-plan-validator.ts

Validation Result Structure

interface ValidationResult {
  isValid: boolean;
  blockingIssues: string[];
  warningIssues: string[];
  unassignedFiles: FileInventory["files"][number][];
  duplicateAssignments: Array<{ fileId: string; groups: string[] }>;
  unknownPatterns: UnknownPattern[];
  emptyGroups: string[];
}

Sources: src/tools/group/grouping-plan-validator.ts:1-50

Edge Aggregation

Cross-Group Relationship Detection

The assignment engine aggregates edges between groups based on:

1. Import Dependencies: Files importing from other groups
2. Reference Patterns: Cross-module references
3. Test Relationships: Test files referencing implementation files

private aggregateEdges(
  facts: FileFacts,
  fileToGroup: Map<string, string>
): CrossGroupEdge[] {
  // Aggregates file-level edges into group-level edges
  // Groups edges by fromGroupId, toGroupId, and type
  // Returns sorted, deduplicated edge list
}

Sources: src/tools/group/grouping-assignment-engine.ts:200-250

Edge Composition

The compose-output-builder.ts transforms grouping results into the final output format:

edges: [...grouping.crossGroupEdges]
  .sort((a, b) =>
    a.fromGroupId.localeCompare(b.fromGroupId)
    || a.toGroupId.localeCompare(b.toGroupId)
    || a.type.localeCompare(b.type),
  ),

Sources: src/tools/compose/compose-output-builder.ts:1-50

Group Update Workflow

Refresh Integration

When files change in the repository, the Group Tool integrates with the refresh workflow:

graph LR
    A[File Changes] --> B[Refresh Tool]
    B --> C{New unassigned files?}
    C -->|Yes| D[Group Update Tool]
    C -->|No| E[Skip Update]
    D --> F[User Decisions]
    F --> G[Updated Grouping]

Empty Group Detection

The refresh process identifies:

• Unassigned Files: Files not belonging to any group
• Empty Group Candidates: Groups that have lost all their files

const emptyGroupCandidates = output.groups
  .filter((group) => group.fileIds.length === 0)
  .map((group) => ({
    groupId: group.id,
    name: group.name,
    docsPath: group.docsPath,
    deletedFileIds: [],
  }));

Sources: src/tools/group-update/index.ts:1-50

File Categorization

The Group Tool inherits file categorization from the Scan Tool:

Sources: src/tools/scan/scan-file-inventory-builder.ts:1-100

Integration Points

With Scan Tool

The Group Tool receives file inventory data:

• File paths and IDs
• Language detection
• Category classification
• Basic file facts

With Compose Tool

The Group Tool produces GroupingResult containing:

• Structured groups with assigned files
• Cross-group edges for relationship visualization
• Role assignments for documentation

With Refresh Tool

The Group Tool participates in the refresh workflow by:

• Receiving updated file inventory
• Identifying unassigned files
• Detecting empty group candidates

Sources: src/tools/refresh/index.ts:1-100

Error Handling

Unknown Pattern Handling

When a pattern matches no files, the tool provides suggestions:

private unknownPattern(
  inventory: FileInventory,
  pattern: string
): UnknownPattern {
  return {
    pattern,
    reason: "matched no inventory files; the path may be ignored or not inventoried",
    suggestions: this.suggestPaths(inventory, pattern),
  };
}

Suggestion Generation

The tool suggests similar paths when patterns fail to match:

private suggestPaths(
  inventory: FileInventory,
  pattern: string
): string[] {
  const suffix = pattern
    .replaceAll("*", "")
    .replaceAll("?", "")
    .split("/")
    .filter(Boolean)
    .at(-1);
  if (!suffix) return [];
  return inventory.files
    .map((file) => file.path)
    .filter((path) => path.includes(suffix))
    .slice(0, 5);
}

Sources: src/tools/group/grouping-assignment-engine.ts:150-180

Usage in Workflows

Initial Setup Workflow

1. Run blueprint.scan to build file inventory
2. Run blueprint.group with mode: "prepare" to get suggested groupings
3. Review and refine the grouping plan
4. Run blueprint.group with mode: "apply" to apply the plan
5. Run blueprint.compose to generate documentation

Maintenance Workflow

1. Run blueprint.refresh when project structure changes
2. If new files are unassigned, run blueprint.group.update
3. Update affected group documentation as needed

Sources: README.md

Summary

The Group Tool is a critical component in the Blueprint system that transforms raw file inventories into semantic architectural groupings. It provides:

• Pattern-based assignment with flexible glob-like syntax
• Validation ensuring complete and conflict-free groupings
• Edge aggregation for cross-group relationship tracking
• Fallback handling for unassigned files
• Integration with the broader Blueprint workflow (scan → group → compose → refresh)

The tool operates in two modes (prepare and apply) enabling iterative group planning and reliable maintenance workflows.

Related Pages

Related topics: System Architecture, Group Tool

Compose Tool

Overview

The Compose Tool is the final stage in the Blueprint pipeline. It transforms the semantic grouping artifact into a frontend-ready JSON output and generates Markdown documentation for each group. The tool acts as the bridge between the analysis/grouping phases and the viewer UI.

Key Responsibilities:

• Builds the final blueprint.v1 output JSON from stored grouping artifacts
• Determin joining of groups, files, edges, docs paths, and validation data
• Generates group documentation Markdown files from templates
• Writes output artifacts to .blueprint/ directory
• Detects entrypoint files for each group
• Validates the composed output against expected schema

Sources: src/tools/compose/index.ts:1-18

Architecture

The Compose Tool is composed of several interconnected components that work together to produce the final Blueprint output.

Component Overview

graph TD
    subgraph "Compose Tool Components"
        CT[ComposeTool]
        COB[ComposeOutputBuilder]
        CAW[ComposeArtifactWriter]
        CED[ComposeEntrypointDetector]
    end
    
    subgraph "Input Dependencies"
        GR[GroupingResult]
        FI[FileInventory]
        AF[AnalysisFacts]
    end
    
    subgraph "Output Artifacts"
        JSON[blueprint-output.json]
        MD[groups/*.md]
    end
    
    CT --> COB
    CT --> CAW
    CT --> CED
    GR --> CT
    FI --> COB
    AF --> COB
    COB --> JSON
    CAW --> MD

Core Classes

Sources: src/tools/compose/index.ts:19-27

Data Flow

Pipeline Integration

The Compose Tool represents stage 3 of the Blueprint pipeline:

graph LR
    subgraph "Stage 1: Scan"
        SI[scan.tool]
        FI[FileInventory]
        AF[AnalysisFacts]
    end
    
    subgraph "Stage 2: Group"
        GI[group.tool]
        GR[GroupingResult]
    end
    
    subgraph "Stage 3: Compose"
        CI[compose.tool]
        JSON[blueprint.v1 JSON]
        MD[Group Docs]
    end
    
    SI --> FI
    SI --> AF
    GI --> GR
    FI --> CI
    GR --> CI
    AF --> CI
    CI --> JSON
    CI --> MD

Input Dependencies

The Compose Tool requires the following artifacts from previous pipeline stages:

1. GroupingResult - Semantic file groupings with assignments
2. FileInventory - Complete file listing with metadata
3. AnalysisFacts - Code analysis data including imports/exports

Sources: src/tools/compose/index.ts:28-35

ComposeTool Class

The ComposeTool class serves as the main orchestrator, delegating work to specialized components.

export class ComposeTool {
  constructor(
    private readonly outputBuilder: ComposeOutputBuilder,
    private readonly artifactWriter: ComposeArtifactWriter,
  ) {}

The `handle()` Method

The primary entry point that processes compose requests:

async handle(args: ComposeArgs, store: ArtifactStore): Promise<ToolResult>

Flow:

1. Retrieves the grouping artifact from the store
2. Validates grouping artifact existence
3. Delegates JSON building to ComposeOutputBuilder
4. Delegates artifact writing to ComposeArtifactWriter
5. Returns structured tool result

Sources: src/tools/compose/index.ts:28-48

Error Handling

The tool provides descriptive error messages when artifacts are missing:

if (!grouping) {
  const entry = store.get(args.groupingArtifactId);
  return errorResult(
    entry
      ? `Grouping artifact ${args.groupingArtifactId} not found or has the wrong type`
      : `Grouping artifact ${args.groupingArtifactId} not found`,
  );
}

ComposeOutputBuilder

The ComposeOutputBuilder is responsible for constructing the final blueprint.v1 output structure.

Output Structure

The builder produces a stable JSON schema containing:

Building Process

The output builder deterministically joins:

• Groups with their assigned files
• File metadata from inventory
• Edge connections between groups
• Documentation paths
• Validation data

Sources: src/tools/compose/compose-output-builder.ts

ComposeArtifactWriter

The ComposeArtifactWriter handles persistence of composed output to the filesystem.

Write Operations

Group Documentation

The artifact writer generates Markdown files for each group using a standardized template that includes:

• Snapshot - Quick orientation summary
• Responsibilities - Ownership and scope definition
• Core Flow - Runtime behavior and data flow
• Contracts & Invariants - Behavior constraints
• Key Files - Main source file references
• Change Guide - Files that should change together
• Pitfalls - Known risks and common mistakes

Sources: src/lib/group-note-template.ts

ComposeEntrypointDetector

The ComposeEntrypointDetector identifies entrypoint files for each group by analyzing:

• Export patterns
• Module initialization files
• Main/index file conventions
• Dependency injection configurations

API Reference

ComposeArgs

interface ComposeArgs {
  groupingArtifactId: string;  // ID of the grouping artifact to compose
  outputPath?: string;          // Optional custom output path
}

ComposeResponseValidation

interface ComposeResponseValidation {
  valid: boolean;
  errors: ValidationError[];
}

ToolResult

The compose tool returns a ToolResult with either:

• Success: JSON result containing the composed output path
• Error: Descriptive error message explaining the failure

Usage

CLI Usage

blueprint compose <groupingArtifactId>

MCP Tool Usage

{
  "tool": "blueprint.compose",
  "arguments": {
    "groupingArtifactId": "grouping-20240115-143022"
  }
}

Integration with Other Tools

Tool Chain

graph TD
    subgraph "blueprint CLI"
        SCAN[blueprint.scan]
        GROUP[blueprint.group]
        COMPOSE[blueprint.compose]
        REFRESH[blueprint.refresh]
    end
    
    SCAN --> GROUP
    GROUP --> COMPOSE
    COMPOSE --> REFRESH
    REFRESH --> GROUP

Related Tools

Output Schema (blueprint.v1)

interface BlueprintOutput {
  version: "blueprint.v1";
  generated: string;           // ISO timestamp
  groups: Group[];
  files: FileEntry[];
  edges: Edge[];
  metadata: {
    sourceRoot: string;
    artifactCount: number;
  };
  validation: ComposeResponseValidation;
}

Best Practices

1. Always run scan before compose - Ensure fresh analysis data
2. Use stable artifact IDs - Grouping artifacts should be referenced by ID, not path
3. Validate output - Check the validation results before consuming the output
4. Preserve group documentation - The generated Markdown files should be version-controlled

File Structure

.blueprint/
├── blueprint-output.json    # Main Blueprint JSON (blueprint.v1)
├── brief.md                 # Project overview
└── groups/
    ├── group-1.md           # Group-specific documentation
    ├── group-2.md
    └── ...

Related Pages

Related topics: System Architecture, Compose Tool

I cannot generate an accurate technical wiki page about the Refresh Tool based on the provided context. The requested source files are not present in the retrieved repository content:

Missing Source Files:

• src/tools/refresh/index.ts
• src/tools/refresh/refresh.types.ts
• src/tools/group-update/index.ts
• src/tools/group-update/group-update-applier.ts

Available Context: The README.md does reference blueprint.refresh as a tool that "Refreshes Blueprint state from the current filesystem snapshot" and blueprint.group.update for "Assigning unassigned files or managing empty groups after refresh," but the actual implementation source code for these components is not included in the provided context.

To generate an accurate wiki page, I would need access to the actual source files for the refresh and group-update tools.

Related Pages

Related topics: System Architecture, MCP Server Implementation

Task Context Tool

The requested source file src/tools/task-context.ts was not found in the provided repository context. This wiki page cannot be generated with the specified source file.

Related Pages

Related topics: System Architecture

Viewer Frontend

Overview

The Viewer Frontend is a lightweight React-based interface for exploring and navigating Blueprint project documentation. It provides an interactive visualization layer that renders the output generated by Blueprint's compose stage, enabling developers to browse groups, files, connections, and architectural documentation through a visual canvas or detailed panel views.

The viewer is designed as a static, self-contained HTML artifact that can be opened in any browser without requiring a dedicated HTTP server. This approach prioritizes portability and simplicity, allowing teams to commit the generated viewer HTML alongside their project documentation.

Architecture

High-Level Design

graph TD
    subgraph "Data Sources"
        A[blueprint-output.json] --> D[BlueprintViewerService]
        B[groups/*.md] --> D
    end
    
    subgraph "Application Layer"
        D --> E[BlueprintApp]
        E --> F[BlueprintCanvas]
        E --> G[GroupDetailPanel]
    end
    
    subgraph "Rendering"
        F --> H[BlueprintExplorer]
        G --> I[SectionCard]
        G --> J[ConnectionDiagram]
        G --> K[OpenQuestionsCards]
    end
    
    E --> L[index.html]

The viewer follows a service-based architecture that abstracts data access through BlueprintViewerService. This design supports multiple data source modes: embedded JSON data for static viewing or HTTP fetching for development workflows.

Component Hierarchy

Core Components

BlueprintApp

The main application shell that orchestrates the viewer experience. It maintains the active tab state and determines which view to render based on user interaction.

State Management:

• activeTab: Tracks whether the user is viewing the canvas or a specific group's details
• activeGroupId: Identifies the currently selected group for detail view
• overview: Contains the complete Blueprint data including all groups, files, and connections

Tab Types:

• canvas: The full project visualization showing all groups and their relationships
• group: Detailed view of a specific group with its documentation

// Tab structure from BlueprintApp.tsx
activeTab.type === "canvas" 
  ? <BlueprintCanvas overview={overview} activeGroupId={activeGroupId} onGroupClick={openGroup} />
  : <GroupDetailPanel detail={details[activeTab.group.id]} />

GroupDetailPanel

The primary content display component that renders detailed documentation for a selected group. It organizes content into logical sub-tabs.

graph LR
    A[GroupDetailPanel] --> B[overview]
    A --> C[files]
    A --> D[connections]
    A --> E[architecture]
    A --> F[guide]
    
    B --> B1[Snapshot]
    B --> B2[Responsibilities]
    B --> B3[Key Files]
    B --> B4[Open Questions]
    
    E --> E1[Core Flow]
    E --> E2[Contracts & Invariants]
    E --> E3[Key Files]
    
    F --> F1[Change Guide]
    F --> F2[Contracts & Invariants]
    F --> F3[Pitfalls]
    F --> F4[Tests]
    F --> F5[Debugging]
    F --> F6[Extension / Open Questions]

Sub-Tabs and Content:

SectionCard Component

A reusable collapsible component for rendering markdown content sections within the detail panel.

Features:

• Expandable/collapsible with smooth animation
• Preview text when collapsed (line-clamp-1)
• Configurable title styling with accent colors
• Markdown content rendering via SectionContent

Animation Behavior:

// Entrance/exit animations
<motion.div
  initial={{ height: 0, opacity: 0 }}
  animate={{ height: 'auto', opacity: 1 }}
  exit={{ height: 0, opacity: 0 }}
  transition={{ duration: 0.2 }}
>

Data Flow

Static Viewer Data Model

The viewer expects a structured JSON input that is either embedded in the HTML or fetched from the filesystem. The data model follows the blueprint.v1 schema.

sequenceDiagram
    participant User as User Browser
    participant HTML as index.html
    participant Service as BlueprintViewerService
    participant Store as Artifact Store
    
    User->>HTML: Open .blueprint/index.html
    HTML->>Service: Initialize with embedded data
    Service->>Store: Parse blueprint-output.json
    Store->>HTML: Render overview
    User->>HTML: Click group
    HTML->>Service: Request group details
    Service->>Store: Load groups/*.md files
    Store->>HTML: Render GroupDetailPanel

Data Source Abstraction

The viewer uses a BlueprintDataSource abstraction layer that supports two modes:

Static Viewer Generation

Build Process

The viewer is generated by the blueprint compose command, which produces a self-contained HTML file. According to the project roadmap, the generation process follows these principles:

1. Inline all assets: JavaScript and CSS are bundled directly into the HTML
2. Safe JSON embedding: Data is embedded using <script id="blueprint-data" type="application/json"> with proper escaping
3. Security considerations: XSS and </script> closing tag risks are mitigated through escaping

CLI Commands

Output Artifacts

UI/UX Design

Visual Design System

The viewer uses a zinc-based color palette with specific accent colors for semantic meaning:

Typography

Animation Guidelines

The viewer uses Framer Motion for animations with consistent timing:

Group Documentation Template

Groups follow a standardized documentation template that the viewer renders:

AGENTS.md Integration

The viewer supports integration with the agent instruction system. The renderBlueprintAgentsSnippet() function generates a standardized marker-delimited section that can be injected into project documentation:

<!-- BLUEPRINT-AGENTS-BEGIN -->

## Blueprint MCP

This project uses Blueprint MCP for local architecture memory.

Before broad codebase exploration, read:

`node_modules/blueprint-mcp-server/docs/agents.md`

If Blueprint memory exists, start with:

`.blueprint/brief.md`

<!-- BLUEPRINT-AGENTS-END -->

This enables tools and agents to discover and use Blueprint documentation automatically.

Development Workflow

Running the Viewer During Development

``bash blueprint.scan blueprint.group --mode prepare blueprint.group --mode apply blueprint.compose ``

1. Initial scan and compose:

``bash blueprint open ``

1. Open the viewer:

``bash blueprint open --watch ``

1. Watch for changes:

Maintenance Workflow

When project files change significantly:

1. Run blueprint.refresh to update the file inventory
2. Run blueprint.group.update if new files are unassigned
3. Update affected .blueprint/groups/*.md notes
4. Regenerate the viewer with blueprint open

Browser Compatibility

The viewer is built with React 18 and Vite, targeting modern browsers with ESM support. No additional polyfills are included in the static bundle.

Security Model

The static viewer follows security best practices:

• All data is embedded directly in the HTML, eliminating network-based attacks
• JSON data is escaped before embedding to prevent XSS via </script> injection
• Special characters (<, -->, \u2028, \u2029) are properly escaped
• No eval() or dynamic code execution from embedded data

Doramagic Pitfall Log

Doramagic extracted 6 source-linked risk signals. Review them before installing or handing real data to the project.

1. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.

2. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing

3. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium

5. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown

6. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using blueprint with real data or production workflows.

• README/documentation is current enough for a first validation pass. - GitHub / issue