High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub is a graph-based infrastructure data management platform that provides Git-like branching and version control for infrastructure data. It integrates a flexible graph database with a modern API layer to ensure data integrity and temporal awareness across all infrastructure resources.
Sources: AGENTS.md:3-6, dev/constitution.md:46-47
The system manages infrastructure data through a schema-driven approach where every node, attribute, and relationship must be defined in the schema layer before it exists in the database.
Sources: dev/constitution.md:27-30
System Components
Infrahub consists of several primary components that interact to provide data management, visualization, and automation capabilities.
| Component | Description | Primary Technology |
|---|---|---|
| Backend | Handles API requests, domain logic, and database interactions. | Python (FastAPI) |
| Frontend | Provides the web user interface for data management and visualization. | React / TypeScript |
| Database | Stores infrastructure data in a temporal graph format. | Neo4j |
| Task Runner | Manages asynchronous background tasks and workflows. | Prefect |
| SDK | Provides a Python client for interacting with Infrahub programmatically. | Python |
Sources: AGENTS.md:12-19, backend/AGENTS.md:5, dev/constitution.md:95-97
Backend Architecture
The backend utilizes an async-first architecture centered on FastAPI and Neo4j. It is organized into distinct modules that separate API handling, domain logic, and data persistence.
Sources: backend/AGENTS.md:5-18
Layered Structure
- API Layer: Handles REST and GraphQL endpoints. It includes an admission controller for priority-aware load shedding to prevent system saturation.
- Core Layer: Contains the primary domain logic for nodes, schemas, human-friendly identifiers (HFID), and branch differencing.
- Database Layer: Manages Cypher query execution through a specialized
Queryclass pattern to ensure efficient graph traversals. - Worker Layer: Executes background tasks using Prefect, handling asynchronous operations like data synchronization and computed attribute recalculations.
Sources: backend/AGENTS.md:7-18, backend/AGENTS.md:53-56, dev/README.md:49-50
Logic Flow Diagram
The following diagram illustrates the request flow from the API layer through the core domain logic to the graph database.
The diagram shows how requests are gated by admission and authentication before reaching the core logic and the database.
Sources: backend/AGENTS.md:7-18, dev/constitution.md:117-120
Frontend Architecture
The frontend follows a "Clean Architecture" approach, utilizing an entity layer pattern to decouple the user interface from API implementations.
Sources: frontend/app/AGENTS.md:26-37, dev/README.md:58-60
Entity Layer Pattern
| Layer | Responsibility |
|---|---|
| UI Layer | React components that render data and handle user interactions. |
| Domain Layer | Defines models and business logic independent of the API. |
| API Layer | Handles GraphQL and REST communication and data mapping. |
Sources: frontend/app/AGENTS.md:31-33, dev/README.md:58-60
Frontend Data Flow
This diagram represents the separation of concerns within the frontend application.
The domain layer acts as a buffer between the UI and the external API, ensuring that changes in the backend API do not immediately break UI components.
Sources: frontend/app/AGENTS.md:31-33, dev/README.md:58-60
Data Model and Integrity
Infrahub uses a temporal graph model in Neo4j to support branching. Data integrity is enforced via a strict schema-driven principles.
Sources: dev/constitution.md:27-30, dev/constitution.md:46-47
Branch-Safe Design
Every feature must operate correctly across multiple branches and points in time. The system uses a specific priority ordering for resolving edges: branch_level DESC, from DESC, status ASC. Database queries must always include branch and temporal filters.
Sources: dev/constitution.md:46-55
Schema Integrity Rules
- Single Source of Truth: The schema defines all node types, attributes, and relationships.
- Validation: All writes must validate against the active schema for the target branch and timestamp.
- Generated Code: Protocols and core schema files are generated from the schema and must not be edited manually.
Sources: dev/constitution.md:27-38, backend/AGENTS.md:104-106
Documentation Architecture
Technical knowledge is organized following the Diataxis framework to ensure consistency for both human developers and AI agents.
Sources: dev/guidelines/documentation.md:8-13, dev/documentation-architecture.md:6-10
Context Nuggets Pattern
Documentation is broken into small, focused files (200-400 lines) known as "context nuggets."
- Guidelines: Prescriptive rules on how to write code.
- Knowledge: Descriptive references on how the system works.
- Guides: Step-by-step procedures for specific tasks.
- ADRs: Architecture Decision Records explaining the rationale behind major decisions.
Sources: dev/guidelines/repository-organization.md:7-10, dev/README.md:17-27
Navigation and Routing
The root AGENTS.md acts as a lightweight map to orient users and agents. Component-level AGENTS.md files (in backend/, frontend/app/, etc.) serve as indices for their respective areas.
Sources: dev/documentation-architecture.md:6-10, dev/guidelines/repository-organization.md:13-16
Conclusion
The Infrahub architecture prioritizes data integrity through its schema-driven approach and temporal graph model. By separating concerns into distinct backend layers and a structured frontend entity pattern, the system supports complex infrastructure management tasks while maintaining the flexibility of Git-like branching.
Sources: dev/constitution.md:27-30, dev/constitution.md:46-50, frontend/app/AGENTS.md:31-33