Architecture Overview

This section provides detailed technical documentation of Seed's internal architecture.

System Design

Seed is built as an Express-based HTTP server with middleware-driven authentication and MCP protocol implementation.

Core Components

Authentication & Security

• Authentication Middleware - JWT validation on all requests except public paths
• JWKS Service - JSON Web Key Set management with caching and automatic refresh
• Origin Validation - DNS rebinding protection with configurable allowed origins
• OAuth Proxy - OAuth 2.1 implementation with PKCE support for Dynamic Client Registration
• Token Revocation - ✅ IMPLEMENTED (2026-01-06) - RFC 7009 compliant token revocation

MCP Implementation

• MCP Server - Model Context Protocol implementation using @modelcontextprotocol/sdk
• Session Management - Hybrid storage with in-memory transports and Redis-backed metadata
• Client Store - Redis-backed storage for registered OAuth clients with TTL support
• Graceful Shutdown - ✅ IMPLEMENTED (2026-01-06) - Signal handling with proper cleanup

Observability & Performance

• Distributed Rate Limiting - Redis-backed sliding window rate limiting
• Metrics Collection - Prometheus metrics for HTTP requests, MCP operations, and Redis
• Structured Logging - Winston-based logging with JSON and simple formats
• Health Checks - ✅ IMPLEMENTED (2026-01-06) - Liveness and readiness probes
• Configuration Validation - ✅ IMPLEMENTED (2026-01-06) - Startup validation
• Redis Resilience - ✅ IMPLEMENTED (2026-01-06) - Circuit breaker pattern
• Security Headers - Helmet configuration for production security

Technology Stack

Component	Technology	Purpose
Runtime	Node.js 24+	JavaScript runtime
Language	TypeScript	Type safety and developer experience
Framework	Express 5.x	HTTP server and routing
MCP SDK	@modelcontextprotocol/sdk	MCP protocol implementation
JWT	jose	JWT validation and JWKS handling
Storage	ioredis	Redis client for sessions, DCR, and rate limiting
Observability	prom-client	Prometheus metrics collection
Logging	winston	Structured logging with JSON/simple formats
HTTP Logging	morgan	HTTP request/response logging
Security	helmet	Security headers (CSP, HSTS, etc.)
Validation	zod	Schema validation and type safety
Testing	Vitest	Unit and integration testing

Project Structure

src/
├── config/          # Configuration management
│   ├── cors.ts          # CORS configuration with allowed origins
│   ├── dcr.ts           # Dynamic Client Registration settings
│   ├── helmet.ts        # Security headers configuration
│   ├── logging.ts       # Log level and format settings
│   ├── metrics.ts       # Prometheus metrics configuration
│   ├── oidc.ts          # OIDC provider configuration
│   ├── rate-limit.ts    # Rate limiting configuration
│   ├── security.ts      # Origin validation and security
│   └── session.ts       # MCP session configuration
├── middleware/      # Express middleware
│   ├── auth.ts              # JWT authentication middleware
│   ├── distributed-rate-limit.ts  # Redis-backed rate limiting
│   ├── metrics.ts           # Prometheus metrics collection
│   └── origin-validation.ts # DNS rebinding protection
├── mcp/            # MCP server and tools
│   ├── mcp.ts           # MCP server initialization
│   └── tools/           # MCP tool implementations
├── routes/         # HTTP route handlers
│   ├── health.ts        # Health check endpoint
│   ├── mcp.ts          # MCP protocol endpoint
│   └── oauth/          # OAuth 2.1 endpoints
├── services/       # Business logic
│   ├── client-store.ts  # Redis-backed OAuth client storage
│   ├── jwks.ts         # JWKS fetching and caching
│   ├── logger.ts       # Winston logger configuration
│   ├── metrics.ts      # Prometheus metrics definitions
│   ├── redis.ts        # Redis client initialization
│   └── session-store.ts # MCP session storage
└── types/          # TypeScript type definitions

Explore Further

Core Architecture

• Middleware Architecture - Request processing pipeline and middleware layers
• API Endpoints - Complete HTTP API reference
• Error Handling - Standardized error response formats

Authentication & Security

• Authentication Flow - JWT validation with JWKS
• OAuth 2.1 Implementation - Authorization code flow with PKCE and token revocation
• Token Refresh - Automatic token refresh with proactive/reactive strategies
• Security - Defense-in-depth security layers
• Rate Limiting - Distributed rate limiting with Redis

MCP Protocol

• MCP Server Design - Tool, prompt, and resource registration
• Session Management - Hybrid session storage and lifecycle

Operations

• Configuration System - Environment-based configuration with startup validation
• Observability - Prometheus metrics, structured logging, and health checks
• Redis Resilience - Circuit breaker pattern for Redis failures