Skip to content

architecture.md

Latest commit

 

History

History
187 lines (151 loc) · 7.52 KB

architecture.md

File metadata and controls

187 lines (151 loc) · 7.52 KB

Architecture

MCP GitHub Project Manager follows Clean Architecture principles with clear separation of concerns.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                      MCP Layer                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Tool Defs   │  │ Resources   │  │ Request Handling    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ ProjectMgmt     │  │ AI Services     │  │ Planning    │  │
│  │ Service         │  │ (PRD, Tasks)    │  │ Services    │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                 Infrastructure Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ GitHub API  │  │ Caching     │  │ Resilience          │  │
│  │ Repositories│  │ & Events    │  │ (Circuit Breaker)   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                    Domain Layer                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Entities    │  │ Interfaces  │  │ Zod Schemas         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Layer Structure

Domain Layer (src/domain/)

Core business entities and type definitions:

File Purpose
types.ts Core project, issue, milestone types
ai-types.ts AI task generation and PRD types
resource-schemas.ts Zod schemas for validation
errors.ts Domain-specific error types

Infrastructure Layer (src/infrastructure/)

External integrations and technical concerns:

Directory Purpose
github/ GitHub REST/GraphQL API integration
tools/ MCP tool definitions (116 tools)
cache/ In-memory caching with TTL
resilience/ Circuit breaker, retry policies
events/ Webhook handling, event store
health/ Health check endpoints

Service Layer (src/services/)

Business logic coordination (17 services):

Service Responsibility
ProjectManagementService Central orchestrator for project operations
PRDGenerationService AI-powered PRD generation
TaskGenerationService Task breakdown and estimation
SprintPlanningService Sprint planning and capacity
RoadmapPlanningService Milestone and roadmap planning
SubIssueService Hierarchical issue management
ProjectTemplateService Template management
IssueTriagingService AI-powered issue triage

MCP Layer (src/index.ts)

Model Context Protocol integration:

  • Tool registration and execution
  • Resource exposure
  • Request/response handling
  • Error formatting

Key Patterns

Dependency Injection

Uses tsyringe for IoC:

// src/container.ts
container.register("ProjectManagementService", {
  useFactory: (c) => new ProjectManagementService(
    c.resolve("GitHubProjectRepository"),
    c.resolve("GitHubIssueRepository"),
    // ...
  )
});

Repository Pattern

Abstracts data access:

// Domain interface
interface IProjectRepository {
  findById(id: string): Promise<Project>;
  save(project: Project): Promise<void>;
}

// Infrastructure implementation
class GitHubProjectRepository implements IProjectRepository {
  // GitHub API calls
}

Circuit Breaker

Resilience for external APIs:

// Wraps GitHub API calls
const result = await circuitBreaker.execute(() =>
  this.octokit.projects.get({ project_id })
);

Data Flow

MCP Client Request
       │
       ▼
┌─────────────────┐
│  Tool Handler   │  ← Validates input with Zod
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Service      │  ← Business logic
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Repository     │  ← Data access abstraction
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  GitHub API     │  ← REST/GraphQL calls
└─────────────────┘

AI Integration

Multi-provider AI support:

┌─────────────────────────────────────┐
│         AIServiceFactory            │
├─────────────────────────────────────┤
│  ┌─────────┐ ┌─────────┐ ┌───────┐ │
│  │Anthropic│ │ OpenAI  │ │Google │ │
│  └─────────┘ └─────────┘ └───────┘ │
└─────────────────────────────────────┘

Used for:

  • PRD generation and enhancement
  • Task complexity analysis
  • Issue enrichment and triage
  • Label suggestions
  • Duplicate detection

Configuration

Environment-based configuration:

Variable Purpose
GITHUB_TOKEN GitHub API authentication
GITHUB_OWNER Repository owner
GITHUB_REPO Repository name
ANTHROPIC_API_KEY Claude AI (optional)
OPENAI_API_KEY OpenAI (optional)
GOOGLE_AI_API_KEY Google AI (optional)

See CONFIGURATION.md for full details.