Architecture Overview¶

Philosophy¶

MCP DevKit is structured as a modular monolith with a monorepo approach using pnpm workspaces. The backend is built using NestJS and strict module boundaries enforced by the framework's dependency injection system, while background tasks and frontend dashboards reside in their own discrete applications within the monorepo.

Why a Modular Monolith?¶

Rather than creating dozens of microservices on day one, the modular monolith gives us:

Simple deployment - one Docker Compose composition to deploy to a single node.
In-process execution - no serialization overhead for synchronous intra-module communication.
Shared infrastructure - a single PostgreSQL instance and Redis cache.
Extensibility - as modules grow (e.g., the worker processing MCP tool invocations), they can be shifted into independent scaling groups.

Data Flow¶

Client / MCP Agent
    │
    ▼
Middleware (correlation ID → request logging)
    │
    ▼
Guards (authentication, future RBAC policies)
    │
    ▼
Pipes (validation, transformation)
    │
    ▼
Controller (route handling)
    │
    ▼
Service (business logic / policy enforcement)
    │
    ├──▶ PrismaService (metadata, DB proxy)
    ├──▶ RedisService (rate limiting)
    └──▶ Worker / External MCP Server (invocation)
    │
    ▼
Interceptor (response serialization, audit logging)
    │
    ▼
Exception Filter (error formatting)
    │
    ▼
Response

Infrastructure¶

Service	Component	Port	Purpose
PostgreSQL 17	`postgres`	5432	Primary database for metadata, policies, audit log
Redis 7	`redis`	6379	Caching, rate limiting, and BullMQ task queues
MCP Backend	`apps/api`	3000	Primary API and agent ingress point

All services run via Docker Compose.

Project Structure¶

mcp-devkit/
├── apps/
│   ├── api/            ← NestJS backend (Core execution & APIs)
│   ├── web/            ← React + Vite dashboard (Phase 6A)
│   └── worker/         ← BullMQ background jobs (Phase 2+)
├── packages/
│   └── shared/         ← Shared types, DTOs, and constants
├── docs/               ← Current domain documentation
├── docker-compose.yml  ← Infrastructure (Postgres + Redis)
└── .github/workflows/  ← CI/CD pipeline

Each app is responsible for its own domain, and communication is heavily standardized via packages within the monorepo workspace.