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 Score
- A Setup Readiness Score
- Category-level score breakdowns
- Setup gaps, architecture violations, and guidance findings
- 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 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.
Setup gaps, violations, and guidance
Setup gaps are missing or incomplete ArchPilot configuration, contracts, or supporting artifacts. They affect setup readiness and should be fixed so validation has enough context.
Architecture violations are rule breaches in the modeled architecture, dependency graph, contracts, policy, or related code evidence. Guidance findings explain useful next steps without implying the same severity as a violation.
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.
Implemented validation categories
The current implemented catalog includes the existing architecture, dependency, ADR, documentation, safety, suppression, API, and database setup rules, plus focused categories for Application Layering, Authorization, Tenant Isolation, Transaction Boundaries, Domain Model Quality, API Design, Data / Query Risk, and Event Architecture.
Each rule detail page documents the rule ID, title, category, severity, explanation, example violation, and remediation guidance from the current catalog.
- Application Layering: AP-APP-001 through AP-APP-005.
- Authorization: AP-AUTH-001 through AP-AUTH-003.
- Tenant Isolation: AP-TEN-001 through AP-TEN-004.
- Transaction Boundaries: AP-TXN-001 through AP-TXN-004.
- Domain Model Quality: AP-DOM-001 through AP-DOM-005.
- API Design: AP-API-010 through AP-API-015.
- Data / Query Risk: AP-DQR-001 through AP-DQR-008.
- Event Architecture: AP-EVT-001 through AP-EVT-004.
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