Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub manages infrastructure data foundation for modern automation by combining graph-based data modeling with Git-like version control. It unifies fragmented data into repeatable, validated workflows using Neo4j as its primary data store. The platform provides a schema-first approach to manage devices, services, and topologies while ensuring data integrity through branching and peer review.
Sources: README.md:15-28, AGENTS.md:3-5
Core Architecture and Tech Stack
Infrahub uses a modern, distributed architecture split between a Python backend and a TypeScript frontend. The system relies on Neo4j for relationship-rich data storage and Prefect for background task orchestration.
System Components
This diagram illustrates the high-level interaction between the primary system components.
Sources: AGENTS.md:7-14, backend/AGENTS.md:5-15, README.md:56-78
Technology Requirements
| Component | Technology | Version |
|---|---|---|
| Backend | Python | 3.14 |
| API Framework | FastAPI | 0.131.0 |
| Database | Neo4j | 2026.05 |
| Frontend | TypeScript / React | 5.9 / 19.2 |
| Package Manager | uv (Python) / pnpm (JS) | Latest |
| Task Runner | Invoke | 2.2.1 |
Sources: AGENTS.md:7-13
Initial Development Setup
You must configure the local environment by installing dependencies for both the backend and frontend modules.
Backend Setup
- Clone the repository with its submodules:
git clone --recursive <repo-url>. - Install Python dependencies using the
uvtool:uv sync --all-groups. - Verify the installation by running backend unit tests:
uv run invoke backend.test-unit.
Sources: AGENTS.md:21-23, AGENTS.md:29, dev/guidelines/git-workflow.md:38-40
Frontend Setup
- Navigate to the frontend directory:
cd frontend/app. - Initialize submodules and install dependencies:
pnpm setup. - Start the development server:
pnpm dev.
Sources: frontend/app/AGENTS.md:9-12
Docker Environment
Infrahub uses Docker to manage backing services. Component tests start these services automatically via TestContainers unless configured otherwise.
- To use an existing database for tests, set
INFRAHUB_USE_TEST_CONTAINERS=false. - To build local containers, run
uv run invoke dev.build.
Sources: AGENTS.md:35-37, AGENTS.md:70
Development Principles and Standards
All contributions must adhere to the Infrahub Constitution, which establishes the core engineering requirements for the project.
The Seven Principles
- Schema-Driven Integrity: Define all data structures in the schema layer before they exist in the database.
- Branch-Safe by Default: Ensure code operates correctly across branching and temporal models; do not assume the default branch.
- Type Safety: Use explicit contracts and type hints (Python) or strict types (TypeScript) at all boundaries.
- Test Discipline: Include unit, component, functional, or E2E tests for every new feature.
- Query Efficiency: Optimize database queries for Neo4j from the start, avoiding N+1 patterns.
- Security Boundaries: Validate and sanitize all input at the API layer.
- Simplicity: Prefer the simplest solution and avoid premature abstractions.
Sources: dev/constitution.md:26-118
Repository Structure
Documentation and development assets are organized into specific "Context Nuggets" within the dev/ directory to facilitate discovery.
| Directory | Purpose |
|---|---|
dev/guidelines/ | Prescriptive rules on how to write code. |
dev/knowledge/ | Descriptive reference on how the system works. |
dev/guides/ | Step-by-step procedures for specific tasks. |
dev/specs/ | Approved designs and implementation plans. |
dev/adr/ | Architecture Decision Records explaining why decisions were made. |
Sources: dev/guidelines/repository-organization.md:45-120, dev/documentation-architecture.md:14-25
Quality Control Gates
Before pushing changes, you must pass several local validation checks to satisfy CI requirements.
Python Verification
uv run invoke format # Formats code with ruff
uv run invoke lint # Lints code with ruff and mypy
uv run invoke backend.generate # Regenerates protocols and schemas
Sources: AGENTS.md:58-60, backend/AGENTS.md:23
Frontend Verification
pnpm exec biome ci . # CI-style lint and format
pnpm knip # Checks for unused exports and dependencies
pnpm exec betterer ci # TypeScript regression gate
Sources: frontend/app/AGENTS.md:19-22
Summary
Getting started with Infrahub requires setting up a dual-stack environment (Python and TypeScript) and adhering to schema-driven development principles. By using uv and pnpm, you can quickly prepare the environment for local development while following the constitutional principles ensures that all infrastructure data remains consistent, version-controlled, and validated.
Sources: AGENTS.md:3-14, dev/constitution.md:11-20