Architecture Rules

Review implemented validation rules for architecture configuration, module registry, contracts, and project identity setup.

Why it matters

Architecture findings keep the repository's ArchPilot model usable so rule results point at the right modules, contracts, and project context.

Overview

Review implemented validation rules for architecture configuration, module registry, contracts, and project identity setup.

Architecture findings keep the repository's ArchPilot model usable so rule results point at the right modules, contracts, and project context.

Why it matters

Cloud uses this guidance to help teams interpret local validation findings in organization context without turning the docs into implementation notes.

When this domain drifts, findings become harder to triage, ownership becomes less clear, and architecture review depends too much on individual memory.

Good architectural practices

Architecture configuration that can be parsed and trusted.
Module registry and contract identity that stay aligned.
Project identity and setup evidence suitable for local validation and Cloud snapshots.

Common anti-patterns

Modular monolith folder structure exists
Implementation profile not fully supported
Architecture overview artifact exists
Module baseline files exist
Module registry path exists
Module contract file exists
Module contract identity matches registry
Module public entrypoints are aligned
Project rule configuration file is valid
Invalid ArchPilot project configuration JSON
Invalid ArchPilot project identity configuration

Relationship to other architecture areas

This domain usually overlaps with neighboring validation categories. Use the related pages below to understand the adjacent architecture concerns before changing policy, suppressing a finding, or accepting risk.

Implemented rules

These are the currently implemented rules in this category. Use this table for category-level orientation, then open the Rule Catalog when you need rule-specific examples and remediation guidance.

Rule ID	Rule title	Category	Severity	Short explanation	Example violation	Remediation guidance	Rule detail
AP-ARCH-001	Modular monolith folder structure exists	Architecture	error	Checks that the configured module root exists and contains the expected module directories.	"moduleRoot": "apps/api/src/modules" but modules live under src/features.	Check the configured module root. Move modules back under the configured root or update the architecture configuration. Run validation again after the filesystem and configuration agree.	View rule page
AP-ARCH-002	Implementation profile not fully supported	Architecture	info	Reports when ArchPilot uses default deterministic validation for a recognized implementation profile.	Assuming this guidance means validation is unavailable.	Keep running default validation. Review generated findings and setup guidance. Update ArchPilot tooling as specialized stack coverage expands.	View rule page
AP-ARCH-003	Architecture overview artifact exists	Architecture	error	Checks that the architecture overview document exists.	Validation is configured but no architecture overview is present.	Create or restore the architecture overview. Update configuration if the overview lives elsewhere. Include system boundaries, modules, tenant model, and validation responsibilities.	View rule page
AP-ARCH-004	Module baseline files exist	Architecture	warning	Checks that expected module baseline artifacts are present.	CI expects baseline comparison but no baseline artifact exists.	Create or refresh the module baseline. Commit baseline artifacts if your workflow expects them. Use baseline commands when drift comparison is part of CI.	View rule page
AP-ARCH-005	Module registry path exists	Architecture	error	Checks that registered module paths exist as directories.	The registry lists snapshots, but apps/api/src/modules/snapshots is missing.	Restore the missing module directory or remove the stale registry entry. Update paths after module moves. Run validation to confirm every registered module resolves.	View rule page
AP-ARCH-006	Module contract file exists	Architecture	error	Checks that every registered module contract file resolves.	A module exists but its .archpilot contract path points to a deleted file.	Create or restore the contract file. Update the registry contract path. Keep contract files versioned with module changes.	View rule page
AP-ARCH-007	Module contract identity matches registry	Architecture	error	Checks that module contract identity and field shape align with the registry.	The billing module contract still declares id: payments.	Update the contract identity to match the registry. Fix missing or malformed contract fields. Avoid copying contracts without changing module-specific values.	View rule page
AP-ARCH-008	Module public entrypoints are aligned	Architecture	error	Checks that registered module public entrypoints match the public surfaces declared in module contracts.	A contract lists src/modules/billing/index.ts while consumers import src/modules/billing/internal/ledger.ts.	Open the affected module contract. Update the public entrypoints to match the files that should be imported by other modules. Update imports to use the public entrypoint and rerun validation.	View rule page
AP-ARCH-009	Project rule configuration file is valid	Architecture	error	Checks that the project rule configuration file can be parsed and used.	A dependency rule config contains malformed JSON or unsupported severity values.	Open the rule configuration file and fix schema issues. Remove unsupported fields. Run validation again and review ignored config entries.	View rule page
AP-ARCH-010	Invalid ArchPilot project configuration JSON	Architecture	error	Checks that the ArchPilot project configuration is valid JSON.	{ "project": "api", }	Fix the JSON syntax. Remove merge conflict markers. Validate the file with your editor or JSON parser before rerunning ArchPilot.	View rule page
AP-ARCH-011	Invalid ArchPilot project identity configuration	Architecture	error	Checks that project identity fields are present and usable.	The project config has an empty project name.	Set the project identity fields in configuration. Use Smart Init if the project identity needs to be regenerated. Rerun validation before uploading governance snapshots.	View rule page

Smart Init Dependency Rules & Module Contracts Rule Catalog

Next steps

Dependency Rules Application Layering