# ArchSpec

> Documentation for ArchSpec, the static-analysis architecture linter for Ruby and Rails applications.

Start with getting started and configuration, then use the rule, architecture, CLI, CI, and AI-written-code guides. Source is on [GitHub](https://github.com/crmne/archspec), and the generated [API reference](https://archspecrb.dev/api/) documents the Ruby API.

## Full Documentation

- [Complete documentation](https://archspecrb.dev/llms-full.txt): All canonical pages in one Markdown document.

## Overview

- [Architecture linter for Ruby and Rails](https://archspecrb.dev/): Static architecture linter for Ruby and Rails and a Packwerk alternative. Declare components and boundaries in one file, then check every change in CI.

## Guides

- [Getting Started](https://archspecrb.dev/getting-started/): Install ArchSpec, generate an Archspec.rb file, run your first architecture check, and learn how to interpret a reported violation.
- [Rails Applications](https://archspecrb.dev/rails/): Configure ArchSpec for a conventional Rails application and enforce practical boundaries between controllers, models, services, and helpers.
- [Checking AI-Written Code](https://archspecrb.dev/checking-ai-written-code/): Use ArchSpec as a deterministic architecture guardrail for AI-written Ruby and Rails code, with actionable evidence for every violation.
- [Vanilla Rails Guide](https://archspecrb.dev/vanilla-rails/): Turn 37signals-style vanilla Rails conventions into executable ArchSpec checks for models, controllers, concerns, and directory structure.
- [How It Works](https://archspecrb.dev/how-it-works/): Learn how ArchSpec indexes Ruby files with Rubydex and Prism, builds its model, evaluates rules, and reports architecture diagnostics.

## Rules

- [Architecture rules overview](https://archspecrb.dev/rules/): Browse every ArchSpec rule for dependencies, cycles, constants, method calls, protocols, object usage, concerns, naming, and component structure.
- [Dependencies](https://archspecrb.dev/rules/dependencies/): Use ArchSpec dependency rules to define component allowlists, deny specific dependencies, restrict consumers, and expose public APIs.
- [Method boundary rules](https://archspecrb.dev/rules/methods/): Use ArchSpec method rules to forbid calls to selected APIs or prevent components from defining methods that violate architecture boundaries.
- [Protocols](https://archspecrb.dev/rules/protocols/): Use ArchSpec protocol rules to require classes in a component to implement one method or at least one member of an accepted method set.
- [Object usage rules](https://archspecrb.dev/rules/objects/): Use ArchSpec object rules to prevent one-shot command-object patterns that instantiate a class and immediately invoke a selected method.
- [Constants](https://archspecrb.dev/rules/constants/): Use ArchSpec constant rules to forbid references to named Ruby constants and anything nested beneath them across component boundaries.
- [Dependency cycle rules](https://archspecrb.dev/rules/cycles/): Use ArchSpec cycle rules to detect circular dependencies between declared components and report the concrete evidence that closes each cycle.
- [Components](https://archspecrb.dev/rules/components/): Use ArchSpec component rules to require selected directories to stay empty and report files that violate an intentional project boundary.
- [Concern independence rules](https://archspecrb.dev/rules/concerns/): Use ArchSpec concern rules to keep reusable modules independent from the concrete classes that include them in Ruby and Rails applications.
- [Method naming rules](https://archspecrb.dev/rules/naming/): Use ArchSpec naming rules to select public or private methods and require or forbid exact names, prefixes, suffixes, and regular expressions.

## Architectures

- [Architectures](https://archspecrb.dev/architectures/): Explore ArchSpec architecture presets for Rails, layered, hexagonal, clean, modular monolith, CQRS, event-driven, and Ruby conventions.
- [Rails architecture preset](https://archspecrb.dev/architectures/rails/): Use ArchSpec's Rails architecture preset to enforce MVC boundaries and keep controller-only APIs out of models and services.
- [Vanilla Rails Architecture](https://archspecrb.dev/architectures/vanilla-rails/): Use ArchSpec's vanilla Rails preset to keep behavior on models, protect conventional boundaries, and forbid extra abstraction directories.
- [Layered architecture preset](https://archspecrb.dev/architectures/layered/): Use ArchSpec's layered architecture preset to define ordered application layers, enforce inward dependencies, and detect dependency cycles.
- [Hexagonal](https://archspecrb.dev/architectures/hexagonal/): Use ArchSpec's hexagonal architecture preset to keep domain code and ports independent from adapters and infrastructure concerns.
- [Clean architecture preset](https://archspecrb.dev/architectures/clean/): Use ArchSpec's clean architecture preset to enforce inward dependencies between frameworks, adapters, use cases, and entities in Ruby apps.
- [Modular Monolith](https://archspecrb.dev/architectures/modular-monolith/): Use ArchSpec's modular monolith preset to declare application modules, dependency allowlists, and public APIs for package boundaries.
- [CQRS architecture preset](https://archspecrb.dev/architectures/cqrs/): Use ArchSpec's CQRS preset to separate commands, queries, and read models while preventing query code from calling mutating methods.
- [Event Driven](https://archspecrb.dev/architectures/event-driven/): Use ArchSpec's event-driven preset to keep event definitions independent while controlling dependencies between publishers and subscribers.
- [Ruby Conventions](https://archspecrb.dev/architectures/ruby-conventions/): Use ArchSpec's Ruby conventions preset to enforce idiomatic method names across a project without declaring application components.

## Reference

- [Configuration](https://archspecrb.dev/configuration/): Complete reference for the Archspec.rb DSL, including sources, components, dependency rules, protocols, naming rules, baselines, and presets.
- [ArchSpec command-line interface](https://archspecrb.dev/cli/): Reference every ArchSpec command-line option for checking projects, explaining files, emitting JSON, managing baselines, and choosing config files.