<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 and helps 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 accelerates 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 module boundaries and dependencies
* Enforce architecture rules and contracts
* Detect architectural drift over time
* Generate architecture scores and reports
* Surface architecture feedback in PRs and CI

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

---

## 🧩 Supported Stacks

ArchPilot supports **practical deterministic architecture detection** across modern application stacks.

### Backend

* Node.js / TypeScript
* NestJS
* Express.js
* Java
* Spring / Spring Boot
* Kotlin
* FastAPI
* Django
* Flask
* PHP
* Laravel
* Go
* .NET
* Ruby on Rails

### Frontend

* React
* Next.js
* Angular
* Vue

### Infrastructure

* Terraform
* Ansible

ArchPilot detects stack shape from practical repository evidence - framework markers, manifests, project layout, and source structure - then applies conservative architecture discovery defaults locally.

**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 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/`)
* Dependency validation and module contracts
* ADR (Architecture Decision Record) support
* Drift detection and history tracking
* PR review and CI integration
* Architecture scoring and reporting

---

## 🎯 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

---
