Skip to main content

​
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 63 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:
#TitleCategoryStatusDate
0001Multi-Provider LLM Support via LiteLLMCoreAccepted2025-10-11
0002Fine-Grained Authorization with OpenFGACoreAccepted2025-10-11
0003Dual Observability: OpenTelemetry + LangSmithCoreAccepted2025-10-11
0004MCP StreamableHTTP Transport ProtocolCoreAccepted2025-10-11
0005Type-Safe Agent Responses with Pydantic AICoreAccepted2025-10-11
0006Pluggable Session Storage ArchitectureAuthAccepted2025-10-13
0007Pluggable Authentication Provider PatternAuthAccepted2025-10-13
0008Infisical for Secrets ManagementInfrastructureAccepted2025-10-13
0009Feature Flag System for Gradual RolloutsInfrastructureAccepted2025-10-13
0010LangGraph Functional API over Object-OrientedDevelopmentAccepted2025-10-13
0011Cookiecutter Template for Project GenerationComplianceAccepted2025-10-13
0012Built-In Compliance Framework (GDPR, SOC 2, HIPAA)ComplianceAccepted2025-10-13
0013Multi-Deployment Target StrategyInfrastructureAccepted2025-10-13
0014Pydantic Type Safety StrategyDevelopmentAccepted2025-10-13
0015Memory Checkpointing for Stateful AgentsDevelopmentAccepted2025-10-13
0016Property-Based Testing with HypothesisDevelopmentAccepted2025-10-13
0017Error Handling StrategyDevelopmentAccepted2025-10-13
0018Semantic Versioning StrategyDevelopmentAccepted2025-10-13
0019Async-First ArchitectureDevelopmentAccepted2025-10-13
0020Dual MCP Transport Protocol (STDIO + StreamableHTTP)InfrastructureAccepted2025-10-13
0021CI/CD Pipeline StrategyInfrastructureAccepted2025-10-13
0022Distributed Conversation Checkpointing with RedisDevelopmentAccepted2025-10-15
0023Anthropic Tool Design Best PracticesDevelopmentAccepted2025-10-17
0024Agentic Loop Implementation (Gather-Action-Verify-Repeat)DevelopmentAccepted2025-10-17
0025Anthropic Best Practices - Advanced EnhancementsDevelopmentAccepted2025-10-17
0026Lazy Observability InitializationDevelopmentAccepted2025-10-17
0027Rate Limiting Strategy for API ProtectionInfrastructureAccepted2025-10-20
0028Multi-Layer Caching StrategyInfrastructureAccepted2025-10-20
0029Custom Exception HierarchyDevelopmentAccepted2025-10-20
0030Resilience Patterns for Production SystemsInfrastructureAccepted2025-10-20
0031Keycloak as Authoritative Identity ProviderAuthAccepted2025-10-23
0032JWT Standardization for Multi-Component AuthAuthAccepted2025-10-23
0033Service Principal Design for Machine-to-Machine AuthAuthAccepted2025-10-23
0034API Key to JWT Exchange PatternAuthAccepted2025-10-23
0035Kong Gateway for JWT ValidationAuthAccepted2025-10-23
0036Hybrid Session Model (Stateless JWT + Stateful Redis)AuthAccepted2025-10-23
0037Identity Federation with External IDPsAuthAccepted2025-10-23
0038SCIM 2.0 Implementation for User ProvisioningAuthAccepted2025-10-23
0039OpenFGA Permission Inheritance ModelAuthAccepted2025-10-23
0040GCP GKE Autopilot Deployment StrategyInfrastructureAccepted2025-10-25
0041PostgreSQL for GDPR-Compliant StorageInfrastructureAccepted2025-10-30
0042Dependency Injection Configuration FixesInfrastructureAccepted2025-01-28
0043Cost Monitoring Dashboard for LLM UsageInfrastructureAccepted2025-11-02
0044Test Infrastructure Quick Wins (Phase 1)DevelopmentAccepted2025-11-06
0045Test Infrastructure Phase 2 - Real Infrastructure FoundationDevelopmentAccepted2025-11-06
0046Deployment Configuration TDD InfrastructureInfrastructureAccepted2025-11-06
0047Visual Workflow Builder (Future)DevelopmentProposed2025-11-02
0048PostgreSQL Storage Integration TestsDevelopmentAccepted2025-11-06
0052Pytest-xdist Isolation Strategy with Worker-Scoped ResourcesDevelopmentAccepted2025-01-11
0049Pytest Fixture Consolidation and OrganizationDevelopmentAccepted2025-11-08
0050Dependency Singleton Pattern JustificationCoreAccepted2025-11-08
0051Memorystore Redis ExternalName Service with Cloud DNSInfrastructureAccepted2025-11-10
0053CI/CD Failure Prevention FrameworkInfrastructureAccepted2025-11-12
0054Pod Failure Prevention FrameworkInfrastructureAccepted2025-11-12
0055Diagram Visualization StandardsDevelopmentAccepted2025-11-15
0056AsyncMock Configuration Prevention MechanismsDevelopmentAccepted2025-11-15
0060Database Architecture and Naming ConventionInfrastructureAccepted2025-11-18
0061FastAPI as Web FrameworkCoreAccepted2025-11-18
0062uv for Package ManagementDevelopmentAccepted2025-11-18
0063Mintlify as Documentation PlatformDevelopmentAccepted2025-11-20
0064Pre-commit Hooks StrategyDevelopmentAccepted2025-11-22
0065Ruff for Code QualityDevelopmentAccepted2025-11-25
0066Helm Chart Security Risk AcceptanceSecurityAccepted2025-11-28

​
Design Principles

Based on our ADRs, these principles guide our architecture:
Use pluggable abstractions (LiteLLM, session storage, auth providers) to avoid vendor lock-in and enable easy switching between providers.
Every feature is designed for production use: proper error handling, observability, security, and scalability built-in.
Leverage Python’s type system with Pydantic for runtime validation and static analysis with mypy strict mode.
All I/O operations are async for better scalability and resource utilization in production deployments.
Dual observability (OpenTelemetry + LangSmith) ensures complete visibility into both infrastructure and LLM behavior.
Enterprise-grade security (JWT, OpenFGA, Infisical) and built-in compliance frameworks (GDPR, SOC 2, HIPAA).
Well-documented decisions, comprehensive testing, clear error messages, and developer-friendly tooling.
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: 
## [Number]. [Title]

Date: YYYY-MM-DD

### Status

[Proposed | Accepted | Deprecated | Superseded]

### Context

What problem are we solving? What constraints exist?

### Decision

What solution did we choose and why?

### Consequences

#### Positive Consequences
- Benefits of this decision

#### Negative Consequences
- Drawbacks and limitations

#### Neutral Consequences
- Trade-offs

### Alternatives Considered

1. **Alternative 1**
   - Description
   - Why rejected

### References

- Related documentation
- External resources

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.