Orchestre Architecture Overview

High-Level Architecture

Core Concepts

MCP Server Architecture

Orchestre operates as an MCP (Model Context Protocol) server that provides:

1. Dynamic Prompts: 20 essential prompts that adapt to your project context
2. MCP Tools: 8 specialized tools for project initialization, analysis, and visual context capture
3. Resource System: Contextual access to project knowledge and patterns

How It Works

1. User Interaction: You invoke prompts through Claude Desktop/Code using the MCP protocol
2. Context Discovery: Orchestre analyzes your project structure and existing patterns
3. Adaptive Behavior: Prompts adjust their behavior based on discovered context
4. Tool Execution: MCP tools perform specific operations when needed

Prompt System Architecture

Dynamic Context Adaptation

Template-Aware Behavior

Prompts automatically adapt based on your project template:

• MakerKit Projects: Uses Supabase conventions, understands team/billing structure
• Cloudflare Projects: Optimizes for edge runtime, uses Workers-specific APIs
• React Native Projects: Mobile-first patterns, handles platform-specific code

State-Based Intelligence

Prompts understand your project's lifecycle:

• MVP Phase: Focus on core features, skip premature optimizations
• Scaling Phase: Include performance optimizations, add monitoring
• Production Phase: Emphasize security, error handling, observability

Resource System

URI Scheme

Orchestre uses a custom URI scheme for resource access:

orchestre://[resource-type]/[path]

Examples:

• orchestre://project/prompts.json - Project configuration
• orchestre://memory/features/auth - Feature-specific knowledge
• orchestre://template/makerkit-nextjs/patterns - Template patterns
• orchestre://knowledge/insights - Discovered insights

Resource Types

Type	Purpose	Example Usage
project	Project-specific configuration	Current prompt state, settings
memory	Contextual knowledge storage	Feature documentation, decisions
template	Template-specific resources	Patterns, conventions, examples
knowledge	Discovered patterns and insights	Code patterns, best practices

Memory System Architecture

Distributed Knowledge

Knowledge Lifecycle

1. Discovery: Prompts analyze existing code and documentation
2. Storage: Knowledge stored in contextual CLAUDE.md files
3. Evolution: Documentation evolves with the codebase
4. Retrieval: Future prompts access accumulated knowledge

Tool Architecture

Available Tools

1. initialize_project: Smart template initialization

   • Clones templates or custom repositories
   • Sets up project structure
   • Installs dependencies

2. analyze_project: AI-powered requirement analysis

   • Uses Gemini for complexity assessment
   • Identifies technical requirements
   • Suggests appropriate approach

3. generate_plan: Adaptive implementation planning

   • Creates phased development plans
   • Considers project complexity
   • Optimizes for parallelization

4. install_commands: Orchestre setup

   • Creates .orchestre directory
   • Generates prompts.json configuration
   • Sets up memory templates

Tool Integration

Security Considerations

API Key Management

• API keys stored as environment variables
• Never committed to version control
• Validated before tool execution

File System Access

• Scoped to project directory
• No arbitrary file system access
• Safe path resolution

Memory Isolation

• Project memories isolated
• No cross-project data leakage
• Git-friendly text format

Performance Characteristics

Response Times

• Prompts: < 100ms (in-memory)
• Tools (local): < 1s (file I/O)
• Tools (AI): 2-7s (API calls)
• Resource access: < 50ms

Scalability

• Stateless server design
• Minimal memory footprint
• Efficient file system access
• Cached template data

Future Architecture Considerations

Planned Enhancements

1. Vector embeddings for semantic memory search
2. Graph-based knowledge relationships
3. Multi-modal support for diagrams/images
4. Distributed team knowledge sharing

Extension Points

• Custom resource providers
• Additional AI model support
• Plugin architecture for tools
• Custom prompt templates