Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• dev/guidelines/repository-organization.md
• dev/guidelines/git-workflow.md
• dev/constitution.md
• dev/bug-pipeline/test-writing.md
• frontend/app/AGENTS.md
• dev/documentation-architecture.md

The local development setup for Infrahub provides the necessary environment to build, test, and contribute to the graph-based infrastructure data management platform. This setup covers the Python-based backend, the React-based frontend, and the documentation ecosystem.

Development follows a "Context Nuggets" pattern where documentation and guidelines are stored as small, focused files in the dev/ directory to assist both human developers and AI agents.
Sources: dev/guidelines/repository-organization.md:10-18, AGENTS.md:1-5

Technology Stack

The project utilizes specific tools and frameworks for different layers of the application.

Layer	Technologies
Backend	Python 3.14, FastAPI 0.131.0, Neo4j 2026.05, Pydantic 2.12
Frontend	TypeScript 5.9, React 19.2, Vite 8.0, Tailwind CSS 4.2
Testing	pytest 9.0, Vitest 4.1, Playwright 1.60
Tooling	uv (Python), pnpm (Frontend), Invoke 2.2.1
Linting	ruff 0.15, mypy 2.3, Biome 2.4

Sources: AGENTS.md:12-20

Prerequisites and Initial Setup

To set up the project locally, you must install the required dependencies and initialize submodules.

1. Repository and Submodules

If you are performing a new clone, use the --recursive flag. If the repository is already cloned, update the submodules to match the recorded commits.

git clone --recursive git@github.com:opsmill/infrahub.git
git submodule update --init --recursive

Sources: dev/guidelines/git-workflow.md:31-41

2. Backend Environment

The project uses uv for Python dependency management. Run the following command from the root to install all groups:

uv sync --all-groups

Sources: AGENTS.md:34-35

3. Frontend Environment

The frontend uses pnpm. You must run the setup command first to initialize frontend-specific submodules.

cd frontend/app
pnpm setup
pnpm install

Sources: frontend/app/AGENTS.md:8-12

Development Environment Flow

This diagram illustrates the sequence for initializing a local environment.

Core Development Guidelines

Git Workflow and Versioning

Infrahub derives versions from Git tags using hatch-vcs. You must fetch tags on a fresh clone to avoid resolving a development fallback version. Re-run uv sync after switching commits to refresh the runtime version.
Sources: dev/guidelines/git-workflow.md:19-27

Coding Standards

• Backend: Use type hints for all parameters and return types. Prefer frozen dataclasses for internal data.
• Frontend: any is forbidden. Use unknown with type guards. Non-null assertions (!) must be replaced with proper null checks.
• Database: All writes must validate against the active schema for the target branch.
  Sources: dev/constitution.md:46-56, dev/constitution.md:15-18

Branching Strategy

• develop: Integration branch for new features.
• stable: Production branch.
• Feature branches: Created from develop and merged via PR.
  Sources: dev/guidelines/git-workflow.md:5-9

Testing and Quality Gates

Every feature must include tests. You should write tests before or alongside implementation.
Sources: dev/constitution.md:59-61

Backend Test Types

• Unit tests: Located in tests/unit/. These run in seconds and have no external service dependencies.
• Component tests: Located in tests/component/. These may use databases via TestContainers.
• Integration Docker tests: Full distributed stack for features like computed attributes or schema migrations.
  Sources: dev/constitution.md:63-71

Frontend Test Types

• Vitest: Used for unit and component tests.
• Playwright: Used for E2E tests in tests/e2e/.
  Sources: dev/constitution.md:72-76

Quality Gate Procedure

Before pushing your changes, you must run the following checks locally:

Documentation Architecture

Infrahub documentation is organized to ensure consistency and discoverability. Technical knowledge is centralized in the dev/ directory.
Sources: dev/documentation-architecture.md:5-7

Context Nuggets Structure

Directory	Purpose
explorations/	Rough ideas and early thinking.
specs/	Approved designs and implementation plans.
guidelines/	Prescriptive rules on how to write code.
knowledge/	Descriptive reference on how the system works.
guides/	Step-by-step procedures for specific tasks.
adr/	Permanent records of architectural decisions.

Sources: dev/guidelines/repository-organization.md:27-110

Internal Documentation Rules

• Direct Voice: Use the imperative mood for guides (e.g., "Create a branch").
• No Padding: Remove phrases like "note that" or "it's important to".
• Link, Don't Duplicate: If a rule exists elsewhere, link to it instead of restating it.
• File Size: Target 200-400 lines per file; split files exceeding 500 lines.
  Sources: dev/guidelines/documentation.md:46-58, dev/guidelines/repository-organization.md:162-164

Summary

Setting up the Infrahub local environment requires a combination of Python (uv), Frontend (pnpm), and Docker tools. By adhering to the core principles of schema-driven integrity and branch-safety, and following the standardized Git and documentation workflows, you ensure that contributions maintain the high confidence and correctness required for infrastructure data management.
Sources: dev/constitution.md:9-12, dev/documentation-architecture.md:5-9