<p align="center">
  <img src="https://archpilot.org/media/branding/logo.svg" width="100" />
</p>

<h1 align="center">ArchPilot</h1>

<p align="center">
  Architecture guardrails for AI-native software development
</p>

ArchPilot validates your repository against architecture rules, helping engineering teams move faster with AI-assisted development without sacrificing architectural integrity.

**Your AI writes code. ArchPilot protects architecture.**

<p align="center">
  Validate • Enforce • Measure architecture continuously
</p>

ArchPilot makes architecture **visible, enforceable, and measurable** as your system evolves.

---

## Why this exists

Most teams rely on documentation or tribal knowledge to maintain architecture.

Over time, boundaries blur, dependencies leak, and architectural decisions drift without anyone noticing.

ArchPilot turns architecture into something you can **actually validate, enforce, and track continuously**.

AI accelerates code delivery but architectural drift can accelerate too.

ArchPilot gives teams deterministic architecture guardrails in local development, CI, and governance workflows.

---

## What it does

ArchPilot turns architecture into something you can actually run and verify:

- Validate architecture across modern application stacks
- Validate module boundaries and dependency governance
- Enforce architecture rules and contracts
- Detect architectural drift over time
- Generate architecture scores and reports
- Surface architecture feedback in local development, PRs, and CI

No runtime agents. No external services. Fully deterministic and local-first.

ArchPilot works alongside GitHub Copilot, Claude Code, Codex, Cursor, and other AI coding tools by continuously validating architectural boundaries before architectural drift becomes technical debt.

---

## Supported Stacks

ArchPilot provides **deterministic architecture validation** across modern application stacks using framework-aware analysis and explicit architectural evidence.

### Backend

Framework-aware validation

- Spring / Spring Boot
- NestJS
- Express.js
- FastAPI
- Laravel
- ASP.NET
- Go

Language-aware validation

- Java
- Node.js / TypeScript
- PHP
- Python

Framework detection

- Kotlin
- Django
- Flask
- Ruby on Rails

### Frontend

- React
- Next.js
- Angular
- Vue

### Infrastructure Context

- Terraform
- Ansible

Infrastructure repositories are detected as part of repository architecture discovery. Full architecture validation currently focuses on application stacks.

ArchPilot automatically detects supported stacks from repository evidence including framework markers, dependency metadata, manifests, project layout, source structure, and framework-specific constructs.

Validation remains deterministic and framework-aware. When evidence is ambiguous, ArchPilot intentionally prefers conservative findings over speculative analysis.

**No cloud scanning. No remote indexing. Deterministic local validation.**

---

## Local-first. Cloud-powered.

Start locally in minutes:

- Offline validation
- Local reports and artifacts
- PR review markdown
- CI validation
- Deterministic architecture checks

Then connect to **ArchPilot Cloud** to unlock:

- Repository history and trends
- Findings dashboards
- Team ownership and governance workflows
- Shared policies and exceptions
- Organization-wide architecture visibility
- Continuous governance across repositories

```bash
archpilot cloud status
archpilot cloud connect
archpilot cloud disconnect
```

Cloud setup only asks for your API token.

ArchPilot uses the canonical production API automatically; no server URL setup is required for normal use.

Learn more:

https://archpilot.org/docs

---

## Installation

Install globally:

```bash
npm install -g @archpilotlabs/archpilot
```

Or run without installing:

```bash
npx @archpilotlabs/archpilot --help
```

---

## Quick Start

### 1. Initialize architecture

```bash
archpilot init
```

Creates `.archpilot/` with architecture config, rules, and baseline artifacts.

---

### 2. Run validation

```bash
archpilot validate
```

Example output:

```text
ArchPilot Architecture Review

Result: FAIL
Errors: 2   Warnings: 1
Score: 82 / 100
```

---

### 3. Fix issues

```bash
archpilot fix
```

Applies safe, deterministic fixes for missing architecture artifacts.

---

### 4. Use in CI

```bash
archpilot validate --ci
```

- Fails only on real architecture violations
- Keeps setup issues separate from architecture quality

---

## CLI vs VS Code Extension

ArchPilot works in two ways:

- **CLI (this package)** - validation, CI, automation
- **VS Code Extension** - visual inspector, guided workflows, and architecture exploration

Both use the same validation engine and produce identical results.
The extension enhances developer experience, but is not required.

---

## Key Concepts

### Architecture Health Score

Measures actual architecture quality based on violations.

### Setup Readiness Score

Tracks completeness of configuration and onboarding.

### Findings

- **violation** - real architecture issue
- **setup-gap** - missing config / skipped checks
- **guidance** - non-blocking recommendation

---

## Core Commands

```bash
archpilot init
archpilot validate
archpilot validate --ci
archpilot fix
archpilot impact <file>
archpilot map
archpilot baseline check
archpilot review pr
archpilot review generate
archpilot report
archpilot cloud status
archpilot cloud connect
archpilot cloud disconnect
archpilot diagrams generate
archpilot policy init
archpilot exception init
archpilot safety init
archpilot bootstrap --with-contracts
archpilot contracts generate
archpilot governance upload
```

`archpilot upload` is an intentional shorthand alias for `archpilot governance upload`.

---

## Core Capabilities

- Architecture-as-code (`.archpilot/`)
- Smart Init architecture discovery
- Cross-stack architecture validation
- Dependency governance and module contracts
- ADR (Architecture Decision Record) support
- Drift detection and history tracking
- PR review and CI integration
- Architecture scoring and reporting

---

## Deterministic by Design

ArchPilot intentionally avoids speculative code analysis.

Findings are produced from explicit architectural evidence such as:

- Framework annotations and decorators
- Dependency relationships
- Route and API definitions
- Authorization constructs
- Transaction boundaries
- ORM and query APIs
- Event and messaging infrastructure
- Architecture configuration and contracts

When evidence is ambiguous, ArchPilot prefers not to report a finding rather than generating false positives.

---

## Philosophy

ArchPilot is built on four principles:

- Architecture should be explicit
- Rules should be executable
- Validation should be deterministic
- Feedback should be continuous

---

## License

Proprietary. See LICENSE file for details.

---

## Learn More

- Website: https://archpilot.org
- Documentation: https://archpilot.org/docs
- [Changelog](https://github.com/archpilotlabs/archpilot-vscode/blob/main/packages/cli/CHANGELOG.md)

---
