What should an AI app architecture document contain?
Include the first complete user journey, system boundaries, authoritative records, permissions, important state changes, failure behavior, technical tradeoffs, and acceptance checks. A list of frameworks or a box diagram alone does not explain what happens when two users change the same record.
A PRD describes the product outcome and rules. Architecture assigns responsibility for making those rules hold. An implementation plan orders the work and explains how each outcome will be checked. Keep the three connected, and proportional to the app.
Compare a PRD, architecture, blueprint, and implementation plan →
Copy the software architecture template
Fill in what is known, keep unanswered product questions visible, and remove sections that do not apply. Ask your agent to recommend ordinary technical choices. The template works as a starting document for Cursor, Claude Code, Codex, or a developer; their repository instruction mechanisms differ.
Editable software architecture document
# 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.
Filled example: a shared room-booking app
This is an illustrative example, not a customer project or a tested implementation. Members reserve two studio rooms, find their saved bookings after reopening, and cancel their own bookings. A manager can manage all bookings. Recurring bookings and calendar sync are outside the first release.
For a small studio, this starting shape keeps the number of moving parts low. A separate service, queue, or distributed cache needs a reason tied to actual requirements. The implementer should choose a framework and database after checking the environment and the constraints below.
A reasonable starting architecture for this example
Member or manager
|
v
Booking interface: availability, review, result, My bookings
|
v
Server booking operation: authenticate, authorize, validate
|
v
Authoritative booking records: room, member, interval, status
|
v
Committed result -> interface shows saved booking or conflict
Starting shape: one web app, server-side booking operations,
and one database. These can live in a single deployable app.
The boundaries describe responsibilities, not mandatory microservices.Assign each rule and record to an owner
The interface helps the user choose an available slot. The server and authoritative storage must still reject a conflicting request. A slot that looks free can become occupied between display and submission.
| Concern | Decision for this example | Where it must hold |
|---|---|---|
| Saved bookings | Room, member, start/end time, and status survive reopening. | Authoritative storage; reads return the committed record. |
| Access | Members manage their own bookings; managers manage all. | Server operations check the authenticated role and record owner. |
| Overlap | At most one active booking occupies a room during an overlapping interval. | An atomic storage operation or constraint; a UI check alone is insufficient. |
| Repeat submission | A retry of the same intended booking does not create another booking. | The write operation uses a defined repeat-request policy. |
| Cancellation | The cancelled booking remains identifiable and stops occupying its slot. | One authoritative status transition; availability follows it. |
| Experience | Review room/date/time before saving; explain a conflict next to the attempted booking. | The booking interface and the server’s result response. |
| First-release boundary | Two fixed rooms, member booking/cancellation, and manager controls. | PRD, architecture, implementation plan, and acceptance checks agree. |
Trace one difficult path before coding
Two members request Room A for the same interval. Both screens can initially show availability. Each server request checks identity and permission; the authoritative booking operation accepts at most one conflicting active booking. The losing request receives a conflict result and the interface refreshes availability.
Checking for overlap and inserting a row as two unprotected steps can let both requests succeed. Ask the implementer to show how the chosen database makes the operation atomic, including transaction or constraint behavior. The requirement is one accepted booking; the implementation technique depends on the actual database.
If a response is lost after the write commits, the retry needs to return or identify the intended result without inserting another booking. Choose that repeat-request behavior explicitly rather than leaving the browser to guess whether the save happened.
Verify the architecture through observable behavior
The document is a proposed system direction. These checks test whether the running implementation actually follows it.
- Book a room, sign out, reopen, and find the same saved booking.
- Attempt the same slot from two member sessions; at most one conflicting booking becomes active.
- Try to cancel another member’s booking and confirm access is denied.
- Retry a request after a lost response and check that the intended booking is not duplicated.
- Cancel an owned booking and confirm that the slot becomes available.
- Record the tested environment and version; a local result does not prove the hosted deployment.
Give the architecture to your coding agent
Ask the agent to read the product brief, inspect the repository, and map these responsibilities to real code. Do not prescribe imaginary file paths. If the app is new, have the agent propose a small starting structure and the first complete milestone.
Architecture-to-implementation handoff
Read this architecture and its product brief. Inspect the actual project and describe the responsibilities and important state changes. Identify unanswered rules that materially change the build. Recommend routine technical and UI choices with their tradeoffs. Propose the first complete user outcome, its affected boundaries, and acceptance checks. Preserve the confirmed product rules. Map the plan to real code locations before implementing it.
When a template is enough, and when Driftbreak helps
If you know the product rules and can review the tradeoffs, fill the template and work with your agent. Driftbreak fits when the direction itself needs resolving: what the app should become, which existing behavior must survive, or which conflicting rule should govern. It reasons from the story and evidence supplied to a case and connects confirmed direction to architecture and an implementation campaign. Your agent or developer still implements and verifies the app.