Search docs
Docs searchValidation & Findings
Validation & Findings
ArchPilot validation produces findings, architecture scores, setup readiness, change risk, governance risk, and explainable output for local review and CI.
This is the core architecture validation workflow. It turns local repository structure and dependency behavior into findings that teams can review, act on, and track over time.
What a validation run produces
- Architecture findings with stable rule IDs
- An Architecture Health Score
- A Setup Readiness Score
- Category-level score breakdowns
- Change risk and governance risk assessments
- Optional component and resource metadata when the local architecture model includes it
- Machine-readable and human-readable reports
How to read the scores
Architecture Health Score focuses on architecture quality and rule outcomes.
Setup Readiness Score tracks whether the repository has enough architecture metadata and supporting artifacts for strong validation.
This separation helps teams distinguish architecture problems from onboarding or bootstrap gaps.
How findings are explained
ArchPilot does not stop at a rule ID and a failure message. Findings can include why the rule matters, how to fix it, examples, and pointers to the related architecture file or contract.
Findings can also carry component metadata, such as componentId or component name, and still use module fields for code-level groupings inside that component.
That makes the output more useful for architecture review, dependency validation, and CI architecture validation workflows.
Component-aware examples
- A monorepo can publish separate web, API, worker, and shared-library components.
- A service can include modules for billing, accounts, and notifications while also declaring a queue or database resource.
- A frontend + API + database repository can show findings at the component level while preserving module-level context where the rule reports it.
What this enables
- Faster software architecture review in local development
- Deterministic architecture policy enforcement in CI
- Clearer PR review conversations when architecture changes are involved
- A measurable architecture drift detection foundation across repeated runs