# Software architecture: [app name]

## 1. Product outcome and scope
First user: [who uses this]
Complete journey: [starting state -> actions -> saved/delivered result]
First release: [included outcomes]
Later: [explicit exclusions]
Confirmed product rules: [rules users can rely on]
Unresolved decisions: [question, consequence, owner]

## 2. System boundaries
Interface: [what the user sees and does]
Server responsibilities: [rules that must be enforced outside the UI]
Authoritative storage: [which records settle each important state]
External services: [purpose, owner, and failure behavior]
Request path: [interface -> trusted operation -> storage -> response]

## 3. Records and ownership
[Record | important fields | owner | allowed writers | retention]
Identify relationships and constraints, not just table names.

## 4. Roles and permissions
[Role | may view | may create/change | must be denied]
State where access is enforced and how ownership is checked.

## 5. Important state changes
[Operation | starting state | validation | committed result]
Describe conflicts, repeat requests, cancellation, and retries.
Name the operation that commits each authoritative change.

## 6. UI and experience
Frequent task: [what should be easy]
Attention and costly mistakes: [what must be obvious or prevented]
Loading, empty, success, and failure states: [user-visible behavior]
References/preferences: [supplied direction; optional choices stay optional]

## 7. Technical choices and tradeoffs
[Choice | proposed option | reason | alternatives | reconsider when]
Let the implementer recommend routine engineering choices.
Do not turn an unresolved product rule into an assumed requirement.

## 8. Deployment and operations
Environments and configuration owners: [local/test/production]
Migration and preserved data: [what must survive]
Useful logs: [failures to diagnose; exclude secrets/private payloads]
Recovery or rollback: [how to recover from a failed change]

## 9. Acceptance evidence
Given [starting state], when [action], then [observable result].
Include reopening, another role, a conflicting/repeated action,
and the important failure path. Record environment and version.

## 10. Implementation handoff
Links: [product brief, current code evidence, implementation plan]
Ask the implementer to inspect the project, map these boundaries
to real code, and identify the first complete verified milestone.