Introduction to Infrahub
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 a unified source of truth for modern automation. It combines a schema-first data model with Git-like version control, including branching and peer review, to manage infrastructure as a reliable service. The platform is designed for teams managing networks, data centers, and cloud infrastructure, moving them from fragmented data to repeatable, validated workflows.
Sources: README.md:1-25, AGENTS.md:3-6
The system exposes data through GraphQL and REST APIs, backed by a Neo4j graph database. It integrates with standard automation tools such as Ansible and Nornir, and provides built-in generators to render configurations using Jinja2 or Python. Infrahub also supports AI-assisted development through an MCP server and specialized Infrahub Skills.
Sources: README.md:27-46, backend/AGENTS.md:5-15
Core Capabilities and Architecture
Infrahub operates on a schema-driven architecture where all data structures must be defined before they exist in the database. This ensures data integrity across branches and points in time. The platform architecture consists of several integrated layers:
- Data Model: A schema-first, graph-backed model using Neo4j to manage complex relationships between infrastructure components.
- Version Control: Native support for branching, merging, and diffing of data and schemas.
- Automation Engine: Generators and transforms that produce artifacts from infrastructure data.
- Integration Layer: Connectors for external tools (Git, Ansible, Netbox) and API surfaces (GraphQL, REST, Web UI).
Sources: README.md:27-46, dev/constitution.md:38-48
System Data Flow
The following diagram illustrates how user requests interact with the schema layer and the underlying graph database.
The diagram shows the flow from an external request through security and validation layers into the core database and background task workers.
Sources: backend/AGENTS.md:7-17, dev/constitution.md:162-178
Key System Components
The project is organized into several distinct areas that handle specific parts of the infrastructure lifecycle.
| Component | Description | Technologies |
|---|---|---|
| Backend | Core logic, FastAPI server, and GraphQL/REST API handling. | Python 3.14, FastAPI, Pydantic |
| Frontend | Web UI for interacting with the graph, managing branches, and reviewing changes. | TypeScript, React, Vite, Tailwind |
| Database | Graph storage and relationship management. | Neo4j 2026.05 |
| Workers | Background task orchestration for long-running processes. | Prefect 3.6.13 |
| SDK | Python-based client library and CLI (infrahubctl). | Python |
Sources: AGENTS.md:8-16, backend/AGENTS.md:7-17, README.md:65-85
Core Principles of Operation
Infrahub development is governed by a set of core principles defined in the project's constitution to ensure data reliability and system performance.
Schema-Driven Integrity
All data in Infrahub is governed by schemas. Definitions act as the single source of truth for data structure. Every write operation must validate against the active schema for the target branch and point in time. Migrations must preserve data integrity, including unique indexes and relationship cardinality.
Sources: dev/constitution.md:38-51
Branch-Safe Operations
Every feature must operate correctly within Infrahub's temporal and branching model. Database queries must include branch and temporal filters. The system prioritizes edge activity based on branch_level, time (from), and status. Only branch deletion permits hard-deletes; all other operations use soft-delete semantics.
Sources: dev/constitution.md:58-71
Security and Input Boundaries
Security is enforced at system boundaries through Pydantic models at API endpoints. All user input is validated and sanitized. The system prevents Cypher injection by forbidding string interpolation in database queries, requiring parameter binding instead. Secrets and credentials must never be committed to the repository.
Sources: dev/constitution.md:155-173
Repository Structure
The repository follows the "Context Nuggets" pattern, organizing internal documentation into small, focused files located in the dev/ directory.
This diagram represents the high-level directory structure designed to facilitate both human developers and AI agents.
Sources: dev/documentation-architecture.md:13-30, dev/guidelines/repository-organization.md:28-115
Internal Documentation Categories
- Guidelines: Prescriptive rules on how to write code (e.g., Python, TypeScript, Testing).
- Knowledge: Descriptive documentation explaining how system components work.
- Specs: Technical designs and implementation plans for specific features.
- ADR: Architecture Decision Records documenting the "why" behind major decisions.
- Guides: Step-by-step procedures for specific developer tasks.
Sources: dev/guidelines/repository-organization.md:46-130, dev/documentation-architecture.md:61-80
Development Workflow
Infrahub uses a standardized workflow for introducing changes to the platform. Every user-facing change requires a changelog fragment managed by Towncrier.
- Requirement: Define changes in a spec file under
dev/specs/if they are significant. - Implementation: Write code following the language-specific guidelines in
dev/guidelines/. - Validation: Run automated tests (unit, integration, and E2E) and linting tools.
- Code Generation: Regenerate protocols, schemas, and SDK types using
invoke backend.generate. - Review: Merge changes into
developvia a Pull Request with a diff summary.
Sources: AGENTS.md:73-88, backend/AGENTS.md:35-42, dev/constitution.md:209-222
Summary
Infrahub serves as a robust foundation for infrastructure automation by combining a flexible graph database with rigorous schema validation and Git-like version control. Its architecture prioritizes data integrity and branch safety, ensuring that infrastructure changes are predictable and auditable. By organizing development around clear technical principles and a modular repository structure, the project maintains a high standard for both human and AI-assisted engineering.
Sources: README.md:1-25, dev/constitution.md:12-30, dev/guidelines/repository-organization.md:10-25