Architectural Decision Records (ADRs)
Relevant source files
The following files were used as context for generating this wiki page:
Architectural Decision Records (ADRs) capture the critical design choices and technical rationales that shape the Infrahub MCP Server. These records provide a historical context for why specific architectures, patterns, or tools were selected over alternatives. By documenting these decisions, the project ensures consistency across contributors and maintains a clear technical direction for both human developers and AI agents.
ADRs are stored within the dev/adr/ directory as focused, versioned Markdown files. They serve as a foundational component of the project's documentation lifecycle, where ideas evolve into ADRs or specifications before becoming permanent descriptive Knowledge or prescriptive Guidelines.
Sources: dev/README.md:1-25, dev/adr/0001-context-nuggets-pattern.md:1-20
Documentation Structure and Lifecycle
The project follows the "Context Nuggets" pattern to organize developer documentation. This pattern prioritizes small, focused files over monolithic documents to optimize token usage for AI agents and improve readability for humans.
Documentation Types
| Directory | Purpose | Content Type |
|---|---|---|
dev/adr/ | Architectural Decision Records | Why decisions were made. |
dev/guidelines/ | Prescriptive rules | How code should be written. |
dev/knowledge/ | Descriptive reference | How the system works. |
dev/constitution.md | Project principles | Governance and quality gates. |
Sources: dev/README.md:12-18, dev/adr/0001-context-nuggets-pattern.md:30-45
Documentation Workflow
The documentation lifecycle follows a specific progression from initial ideas to established knowledge.
The diagram shows the transition of concepts from initial ideas through formal decision-making (ADR/Spec) into descriptive knowledge or prescriptive guidelines.
Sources: dev/README.md:21-25
Primary Architectural Decisions
The following records summarize the foundational design choices implemented in the Infrahub MCP Server.
ADR 0001: Context Nuggets Pattern
The project adopted the "Context Nuggets" pattern for repository organization. This decision addresses the lack of scalability in monolithic files like AGENTS.md, which previously caused AI agents to waste tokens by loading irrelevant context. The pattern centralizes internal developer documentation in the dev/ directory, organized by purpose, and uses symlinks to maintain a single source of truth for tools like Claude Code and Speckit.
Sources: dev/adr/0001-context-nuggets-pattern.md:1-60
ADR 0002: Middleware Stack Ordering
The server utilizes a 17-layer middleware stack that is composed once at startup via configure_middleware(). This centralized approach ensures that operational concerns like logging, timing, and security are applied consistently to every request.
The flow illustrates the top-down processing of the 17-layer middleware stack, ensuring security and observability precede tool execution.
Sources: dev/adr/0002-middleware-stack-ordering.md, specs/archive/20260421-144953-production-ready-mcp-server/plan.md:38-45
ADR 0007: Per-Session Branch Scoping
To improve write isolation and recovery, the project moved from process-wide session branches to per-session scoping.
Key Implementation Details:
- State Model:
AppContextusesWeakKeyDictionarykeyed by the session object to store branch information. - Proactive Detection: The system inspects
BranchData.statusto identifyMERGEDorDELETINGbranches before attempting writes. - Reactive Net: A reactive mechanism catches
GraphQLError(read-only/merged status) during mutations to clear session entries and raise retryable errors.
Sources: specs/archive/20260604-141223-session-branch-recovery/tasks.md:130-145
Governance and Quality Gates
All architectural decisions must align with the Infrahub MCP Server Constitution. The Constitution serves as the authoritative reference for development standards and supersedes informal practices.
Core Principles Summary
- MCP Protocol Compliance: All components must conform to the Model Context Protocol specification.
- Infrahub SDK Integration: All Infrahub operations must utilize the
infrahub-sdk. - Branch-Safe by Default: Write operations must be isolated to session branches to protect the default branch.
- Type Safety: The project mandates full type annotations and MyPy cleanliness.
Sources: dev/constitution.md:40-100, dev/constitution.md:215-225
Amendment Process
Changes to the architectural framework or Constitution require:
- A written proposal with rationale.
- Review and approval by a project maintainer.
- A migration plan for affected code.
- A version increment following semantic versioning rules.
Sources: dev/constitution.md:230-245
Conclusion
Architectural Decision Records are essential for maintaining the long-term integrity of the Infrahub MCP Server. By centralizing "why" decisions were made, the project facilitates smoother onboarding for new contributors and provides a robust framework for AI-assisted development. All future architectural changes must be recorded in the dev/adr/ directory and validated against the project Constitution.