Architecture Decision Records (ADRs)
Relevant source files
The following files were used as context for generating this wiki page:
Architecture Decision Records (ADRs) within the Infrahub Python SDK project capture critical design choices, their rationales, and the context in which they were made. These records ensure that foundational principles—such as API parity, backward compatibility, and type safety—are consistently applied across the SDK and its CLI layer, infrahubctl. The ADR process is governed by a project constitution that mandates strict adherence to these principles to maintain stability for downstream consumers like Ansible collections and external applications.
Sources: dev/constitution.md:1-12, AGENTS.md:1-10
Core Architectural Principles
The SDK follows seven non-negotiable core principles that define its architecture and decision-making framework.
I. Async/Sync Dual API Parity
Every public feature must ship on both InfrahubClient (async) and InfrahubClientSync (sync). Method names, signatures, and behaviors must match exactly. This dual-client approach is the SDK's signature contract, preventing regressions for synchronous consumers.
Sources: dev/constitution.md:19-30, AGENTS.md:38-42
II. Layered Architecture and CLI Design
Reusable logic for API interaction and domain rules must reside in the SDK (infrahub_sdk/). The CLI (infrahub_sdk/ctl/) acts as a thin layer restricted to argument parsing, presentation via Rich, and error handling. Developers must not duplicate logic in the CLI that belongs in the SDK.
Sources: dev/constitution.md:46-56, dev/specs/001-end-user-cli/research.md:R1
III. Type Safety and Stability
All function signatures require type hints, and Pydantic v2 models define API and data boundaries. Public API stability is tiered: names exported in infrahub_sdk/__init__.py are guaranteed and require a deprecation path for breaking changes, while internal underscore-prefixed names may change in minor releases.
Sources: dev/constitution.md:33-43, dev/constitution.md:61-65
Decision Flow and Governance
The following diagram illustrates the workflow for architectural decisions, from research to implementation and documentation.
The development workflow enforces quality gates where pull requests are reviewed against the project constitution.
Sources: dev/specs/001-marketplace-api-update/plan.md:Phases, dev/constitution.md:104-108
Summary of Major Architectural Decisions
The following table summarizes key decisions recorded during the evolution of the SDK and CLI.
| Decision Area | Selection | Rationale |
|---|---|---|
| CLI Framework | AsyncTyper | Proven async pattern matching existing SDK utilities. |
| Entry Point | Top-level infrahubctl | Avoids user confusion and duplicates client/config logic. |
| Data Format | YAML / Pydantic | Reuses InfrahubObjectFileData for spec-compliant round-trips. |
| Relationship Handling | HFID Pass-Through | Server resolves HFIDs; eliminates client-side round-trips. |
| Request Headers | X-Priority | Provides interactive-vs-background signal to server. |
Sources: dev/specs/001-end-user-cli/research.md:R1-R8, specs/ihs-259-sdk-x-priority-header/critiques/critique-20260710-164718.md:Executive Summary
Component Relationship Diagram
This diagram shows how architectural decisions bridge the SDK core and its consumers.
The layered architecture ensures that logic is not "stranded" in the CLI, making it accessible to all consumers.
Sources: dev/constitution.md:46-56, tasks.py:27-40
Documentation and Validation
The project mandates that documentation must accurately describe existing behavior. Tools like mdxify and rumdl are used to generate and validate documentation.
- Docs Generation:
uv run invoke docs-generateproduces CLI and SDK reference docs. - Validation: CI runs
docs-validateto ensure the committed documentation matches the current code state.
Sources: tasks.py:64-70, dev/constitution.py:84-93
Architecture Decision Records ensure the Infrahub SDK remains a stable, predictable foundation for infrastructure automation, adhering to strict versioning and development gates.