Writing architecture rules (arch.yaml)

You define your architecture in an arch.yaml file at the root of your repository. AppArch enforces these rules on every PR/MR.

Basic structure

version: 2
style: hexagonal           # clean | hexagonal | layered | custom

layers:
  - { name: presentation,   paths: ["src/ui/**", "apps/mobile/**"] }
  - { name: application,     paths: ["src/use-cases/**"] }
  - { name: domain,          paths: ["src/domain/**"] }
  - { name: infrastructure,  paths: ["src/infra/**"] }

rules:
  - id: RULE-014
    forbid: "presentation → infrastructure"
  - id: RULE-002
    forbid: "domain → *"
    except: ["std", "shared/types"]
  - id: RULE-031
    max_module_loc: 2000

• layers - the layer names and which paths belong to each layer.
• rules - each rule has an id; forbid defines a directional dependency, max_module_loc defines a size threshold.

Starting from templates

Rather than writing from scratch, you can pick a ready-made template: Clean Architecture, Hexagonal, Layered, DDD, Feature-Sliced Design, and more. In the panel, use Rules → Start from template to generate an arch.yaml draft and add it to your repository.

Managing false positives

Each rule has two escape mechanisms:

• except - exempts specific paths/packages in the rule definition.
• ignore - silences individual findings.

You can click “Accept” with a single tap from the PR comment; ArchPilot remembers the context for the rule on the next review.

Project/workspace override

You can toggle rules on or off per project or per workspace in the panel. A rule you disable in the panel is never sent to the collector - it produces no unnecessary findings. Details: Enabling ArchPilot.