System Architecture

Orchestre V3 is built on a modern, modular architecture that leverages the Model Context Protocol (MCP) to transform Claude Code into an intelligent development platform. This page provides a comprehensive overview of how all the pieces fit together.

High-Level Architecture

Core Components

1. MCP Server (src/server.ts)

The heart of Orchestre - an MCP server that:

• Registers tools for Claude Code to use
• Handles communication between Claude and external services
• Manages tool execution and response formatting
• Provides error handling and logging

// Simplified server structure
const server = new MCPServer({
  tools: [
    initializeProjectTool,
    analyzeProjectTool,
    generatePlanTool,
    multiLlmReviewTool,
    researchTool
  ]
});

2. MCP Tools (src/tools/)

Five specialized tools that provide core functionality:

initializeProject.ts

• Purpose: Smart project initialization
• Capabilities: Template selection, structure setup, command installation
• AI Model: None (deterministic)
• Source: src/tools/initializeProject.ts:1-150

analyzeProject.ts

• Purpose: Deep requirements analysis
• Capabilities: Complexity assessment, risk identification, recommendations
• AI Model: Gemini 2.0 Flash Thinking
• Source: src/tools/analyzeProject.ts:1-200

generatePlan.ts

• Purpose: Intelligent project planning
• Capabilities: Phased approach, dependency mapping, time estimation
• AI Model: Gemini 2.0 Flash Thinking
• Source: src/tools/generatePlan.ts:1-250

multiLlmReview.ts

• Purpose: Consensus-based code review
• Capabilities: Multi-perspective analysis, security checks, performance review
• AI Models: GPT-4 + Claude Sonnet
• Source: src/tools/multiLlmReview.ts:1-300

research.ts

• Purpose: Technical research and best practices
• Capabilities: Current trends, implementation patterns, recommendations
• AI Model: GPT-4
• Source: src/tools/research.ts:1-150

3. Dynamic Commands (src/commands/)

Commands are intelligent prompts that orchestrate workflows:

4. Template System (templates/)

Each template is a complete knowledge pack:

Data Flow

1. Command Execution Flow

2. Multi-LLM Review Flow

Memory Management

Distributed Memory Architecture

Orchestre uses a distributed memory system:

1. CLAUDE.md files - Distributed contextual documentation
2. .orchestre/ - Configuration and cache
3. Git - Version control for all memory

Memory File Structure

Each CLAUDE.md file contains relevant context:

# Feature/Module Name

## Overview
What this feature does and why

## Current Status
- Phase: Implementation
- Progress: 75% complete

## Implementation Details
- Key decisions made
- Patterns used
- Integration points

## Next Steps
- Remaining tasks
- Known issues

Integration Points

1. Claude Code Integration

Orchestre integrates seamlessly through MCP:

{
  "mcpServers": {
    "orchestre": {
      "command": "node",
      "args": ["path/to/orchestre/dist/server.js"],
      "env": {
        "GEMINI_API_KEY": "...",
        "OPENAI_API_KEY": "..."
      }
    }
  }
}

2. AI Model Integration

Each model is used for its strengths:

Model	Purpose	Integration
Gemini 2.0	Analysis & Planning	Google AI SDK
GPT-4	Review & Research	OpenAI SDK
Claude 3	Implementation	Native in Claude Code

3. Version Control Integration

Orchestre is designed to work with Git:

• All state is text-based
• Changes are trackable
• Branching is supported
• Merge conflicts are minimal

Security Architecture

API Key Management

• Keys stored in environment variables
• Never committed to version control
• Passed securely to MCP server
• Scoped to specific operations

Code Review Security

• Automated security scanning
• Vulnerability detection
• Best practice enforcement
• Consensus-based validation

Performance Considerations

Caching Strategy

• Tool results cached when appropriate
• Template data cached locally
• AI responses not cached (freshness)

Parallel Processing

• Multiple tools can run concurrently
• Independent tasks distributed
• Results aggregated efficiently

Resource Management

• Minimal memory footprint
• Efficient file operations
• Lazy loading of templates

Extension Points

Adding New Tools

// src/tools/myNewTool.ts
export const myNewTool: ToolDefinition = {
  name: 'my_new_tool',
  description: 'Description of what it does',
  input_schema: {
    type: 'object',
    properties: {
      // Define inputs
    }
  },
  handler: async (args) => {
    // Implementation
  }
};

Adding New Commands

<!-- src/commands/my-command.md -->
# My new command

You are an expert at [specific task].

## Steps
1. Understand the context
2. Apply your expertise
3. Generate solution

## Tools Available
- Use @tool_name for specific operations

Adding New Templates

{
  "name": "my-template",
  "displayName": "My Template",
  "description": "What this template provides",
  "commands": ["custom-command-1", "custom-command-2"],
  "structure": {
    "directories": ["src", "tests"],
    "files": ["README.md", "package.json"]
  }
}

Architecture Principles

1. Separation of Concerns

• Tools handle data operations
• Commands handle orchestration
• Templates provide domain knowledge
• State remains independent

2. Composability

• Tools can be combined
• Commands can call multiple tools
• Templates can extend base functionality
• Workflows can be chained

3. Adaptability

• Commands discover context
• Templates provide patterns
• Tools analyze dynamically
• Implementation adapts

4. Transparency

• All state is human-readable
• All operations are logged
• All decisions are documented
• All changes are tracked

Next Steps

Now that you understand the architecture:

Design Philosophy

Learn why we built it this way

MCP Deep Dive

Understand the protocol

Tools Reference

Detailed tool documentation