Introduction
This section documents the architectural decisions made throughout the development of MCP Server with LangGraph. Each Architecture Decision Record (ADR) captures the context, decision, consequences, and alternatives considered for significant technical choices.What is an ADR? Architecture Decision Records document important architectural decisions along with their context and consequences, providing historical insight for current and future maintainers.
Architecture Decision Records
We maintain 66 ADRs organized into seven categories:New in v2.8: 10 new ADRs (ADRs 31-39) document our enterprise authentication architecture with Keycloak, service principals, API keys, identity federation, and SCIM provisioning. See Keycloak JWT Architecture Overview for details.
Core Architecture (ADRs 1-5)
These foundational decisions shape the entire system:ADR-0001: Multi-Provider LLM
LiteLLM for unified access to 100+ LLM providers
ADR-0002: OpenFGA Authorization
Fine-grained relationship-based access control
ADR-0003: Dual Observability
OpenTelemetry + LangSmith for complete visibility
ADR-0004: MCP StreamableHTTP
Production-ready HTTP transport protocol
ADR-0005: Pydantic AI Integration
Type-safe agent responses and routing
Authentication & Sessions (ADRs 6-7)
Security and session management patterns:ADR-0006: Session Storage
Pluggable session backends (InMemory, Redis)
ADR-0007: Auth Providers
Flexible authentication (InMemory, Keycloak)
Infrastructure & Deployment (ADRs 8-9, 13, 20-21, 27-28, 30)
Infrastructure, deployment, and operational decisions:ADR-0008: Infisical Secrets
Centralized secrets management
ADR-0009: Feature Flags
Gradual rollout and experimentation
ADR-0013: Multi-Deployment
Support for Docker, K8s, Cloud Run, LangGraph Platform
ADR-0020: Dual Transport
STDIO + StreamableHTTP for flexibility
ADR-0021: CI/CD Pipeline
Automated testing and deployment
ADR-0027: Rate Limiting
API protection and traffic control
ADR-0028: Caching Strategy
Multi-layer performance optimization
ADR-0030: Resilience Patterns
Circuit breakers and retry policies
Development & Quality (ADRs 10, 14-19, 22-26, 29)
Code quality, testing, and development practices:ADR-0010: Functional API
LangGraph functional over object-oriented
ADR-0014: Type Safety
Strict typing with Pydantic
ADR-0015: Checkpointing
Stateful conversation persistence
ADR-0016: Property Testing
Hypothesis for edge case discovery
ADR-0017: Error Handling
Consistent error patterns
ADR-0018: Versioning
Semantic versioning strategy
ADR-0019: Async-First
Async by default for scalability
ADR-0022: Distributed Checkpointing
Redis-backed conversation state
ADR-0023: Anthropic Tool Design
Best practices for tool implementations
ADR-0024: Agentic Loop
Gather-Action-Verify-Repeat cycle
ADR-0025: Anthropic Enhancements
Advanced best practices implementation
ADR-0026: Lazy Observability
On-demand telemetry initialization
ADR-0029: Custom Exceptions
Domain-specific error handling
Compliance & Templates (ADRs 11-12)
Compliance frameworks and project templating:ADR-0011: Cookiecutter Template
Reusable project template
ADR-0012: Compliance Framework
Built-in GDPR, SOC 2, HIPAA support
ADR Index
Quick reference table of all architectural decisions:Design Principles
Based on our ADRs, these principles guide our architecture:Flexibility Over Lock-In
Flexibility Over Lock-In
Use pluggable abstractions (LiteLLM, session storage, auth providers) to avoid vendor lock-in and enable easy switching between providers.
Production-Ready Defaults
Production-Ready Defaults
Every feature is designed for production use: proper error handling, observability, security, and scalability built-in.
Type Safety First
Type Safety First
Leverage Python’s type system with Pydantic for runtime validation and static analysis with mypy strict mode.
Async by Default
Async by Default
All I/O operations are async for better scalability and resource utilization in production deployments.
Observable Systems
Observable Systems
Dual observability (OpenTelemetry + LangSmith) ensures complete visibility into both infrastructure and LLM behavior.
Security & Compliance
Security & Compliance
Enterprise-grade security (JWT, OpenFGA, Infisical) and built-in compliance frameworks (GDPR, SOC 2, HIPAA).
Developer Experience
Developer Experience
Well-documented decisions, comprehensive testing, clear error messages, and developer-friendly tooling.
Progressive Enhancement
Progressive Enhancement
Feature flags enable gradual rollouts and A/B testing without deployments.
System Architecture
When to Create an ADR
Create a new ADR when making decisions about:- Technology Choices: Selecting frameworks, libraries, or services
- Architectural Patterns: Adopting new patterns or changing existing ones
- Cross-Cutting Concerns: Security, observability, error handling
- Integration Strategies: How components interact with each other
- Deployment Approaches: Infrastructure and deployment methodologies
- Quality Practices: Testing strategies, code quality standards
ADR Template
When creating a new ADR, use this structure:Related Documentation
Development Guide
Set up your development environment
Testing Guide
Comprehensive testing strategy
Deployment Guide
Deploy to various platforms
Security Guide
Security best practices
Questions about our architecture? Open a discussion on GitHub or review individual ADRs for detailed rationale.