Frontend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub frontend is a modern web application built with React and TypeScript. It functions as the user interface for the graph-based infrastructure data management platform, providing tools for schema visualization, branch management, and data manipulation. The architecture follows a strict layered pattern to separate concerns between raw API communication, domain logic, and user interface presentation.
Sources: AGENTS.md:3-5, frontend/app/AGENTS.md:3-5
Core Tech Stack
The frontend application resides in frontend/app/ and utilizes a suite of modern development tools and libraries.
| Component | Technology |
|---|---|
| Framework | React 19.2 |
| Language | TypeScript 5.9 |
| Build Tool | Vite 8.0 |
| Styling | Tailwind CSS 4.2 |
| Linting/Formatting | Biome 2.4 |
| Package Manager | pnpm |
| Unit Testing | Vitest 4.1 |
| E2E Testing | Playwright 1.60 |
Sources: AGENTS.md:13-17, frontend/app/AGENTS.md:3-5
Architectural Layers (Entity Pattern)
Infrahub implements an "Entity Layer Pattern" consisting of three distinct layers: API, Domain, and UI. This structure ensures that the UI components remain decoupled from the specific shapes of backend GraphQL and REST responses.
1. API Layer
The API layer handles communication with the Infrahub backend. It contains generated GraphQL types, REST type definitions, and raw fetching logic.
- Location:
frontend/app/src/shared/api/ - Responsibility: Fetching data and defining raw data structures as returned by the server.
2. Domain Layer
The Domain layer acts as a bridge between the API and the UI. It transforms raw API responses into stable domain objects that the frontend logic can rely on.
- Responsibility: Business logic, data mapping, and maintaining the "backend-authoritative" rule.
3. UI Layer
The UI layer contains React components, layouts, and styles. It consumes domain objects to render the interface.
- Responsibility: Presentation and user interaction using the
@infrahub/uidesign system.
Sources: frontend/app/AGENTS.md:43-47, dev/README.md:52-54, dev/constitution.md:159-165
Data Flow Diagram
The following diagram illustrates how data flows from a user interaction through the layers to the backend and back.
This diagram shows the vertical dependency flow where the UI relies on Domain models, which in turn rely on API clients.
Sources: frontend/app/AGENTS.md:43, dev/constitution.md:159-165
State and URL Management
The frontend architecture emphasizes "Backend Authority" and URL synchronization.
- URL Sync: The application uses nested routes and tab bars. State ownership often resides in the URL to ensure shareable links and consistent navigation.
- Branches: The frontend is branch-aware. It retrieves the current branch context and identifies the default branch based on deployment configuration.
- Priority: The frontend emits an
X-Priorityheader with requests to assist the backend in priority-aware load shedding.
Sources: frontend/app/AGENTS.md:39-51, dev/README.md:55, dev/constitution.md:27-34
Development Workflow and Quality Gates
The project enforces strict quality gates to prevent regressions and maintain code standards. Developers must run specific checks before pushing code.
CI/CD Local Gates
Before pushing, the following commands are required to pass the local CI gate:
pnpm exec biome ci .: Executes formatting and linting checks.pnpm knip: Identifies unused exports, files, and dependencies.pnpm exec betterer ci: Prevents TypeScript regressions (Betterer is used instead of plaintsc).pnpm test: Runs the Vitest browser-mode test suite.
Sources: frontend/app/AGENTS.md:21-30
TypeScript Standards
- Strict Typing: The
anykeyword is forbidden. Developers must useunknownwith proper type guards. - Safety: Non-null assertions (
!) and type assertions (as) are prohibited in favor of explicit null checks. - Generation: GraphQL types and REST types are generated automatically and should never be hand-edited.
Sources: dev/constitution.md:49-51, dev/constitution.md:162-164, AGENTS.md:92-95
Directory Structure
The repository organizes frontend assets into specific directories under frontend/app/.
| Path | Description |
|---|---|
src/shared/api/ | Generated GraphQL/REST types and API clients. |
src/shared/components/ | Reusable UI components from the design system. |
packages/schema-visualizer/ | Submodule for the graph visualization engine. |
public/ | Static assets. |
Sources: AGENTS.md:76-78, frontend/app/AGENTS.md:48-49, dev/guidelines/repository-organization.md:105-110
Testing Strategy
Infrahub uses a tiered testing approach for the frontend to ensure both logical correctness and visual stability.
Sequence of testing and validation steps performed during development and CI.
Sources: frontend/app/AGENTS.md:21-30, dev/constitution.md:70-76
Summary
The Frontend Architecture of Infrahub is designed for scale and consistency. By utilizing a layered entity pattern, strict TypeScript enforcement, and automated type generation, the system ensures that complex infrastructure data is presented accurately while remaining maintainable for developers.
Sources: frontend/app/AGENTS.md:43, dev/constitution.md:159-165