ARCHITECTURE.md

This file is the top-level map of the system. It should stay concise and point to deeper documents when needed.

System Shape

• Product: [replace with product name]
• Primary user workflow: [replace with main workflow]
• Runtime surfaces: [desktop / web / cli / services / workers]
• Source of truth for product behavior: docs/product-specs/

Domain Map

Domain	Purpose	Primary Entry Points	Related Spec
[domain-a]	[what it owns]	[modules / routes / commands]	[spec path]
[domain-b]	[what it owns]	[modules / routes / commands]	[spec path]

Layer Model

Use a fixed directional model so agents do not invent ad hoc architecture:

Types -> Config -> Repo -> Service -> Runtime -> UI

Cross-cutting concerns should enter through explicit provider or adapter boundaries instead of reaching across layers directly.

Hard Dependency Rules

• Lower layers must not depend on higher layers.
• UI must not bypass runtime or service contracts.
• Data access must enter through repositories or equivalent adapters.
• Shared utilities must remain generic and must not accumulate domain logic.
• New dependencies should be justified in the matching plan or design doc.

Cross-Cutting Interfaces

Concern	Approved Boundary	Notes
Logging and tracing	[provider / utility path]	[structured only, no ad hoc console use]
Auth	[provider path]	[token/session rules]
External APIs	[client or provider path]	[rate limit / retry guidance]
Feature flags	[flag boundary]	[ownership]

Current Hot Spots

• [area that is hardest for agents to change safely]
• [area with weak boundaries or fragile tests]

Change Checklist

When you touch architecture-relevant code:

1. Update this file if the domain map or allowed boundaries changed.
2. Update the related design doc in docs/design-docs/ if the reasoning changed.
3. Add or update an executable check if the rule should be enforced mechanically.