Software Architecture
for Vibe Coders.

Map what runs on a device, what runs on a server, and which data each part owns.

1. 1.1 · Follow one user action7 min

   Trace a user action from screen to database and notification.

2. 1.2 · Web, mobile, or desktop?7 min

   Compare web, mobile, and desktop architectures. Identify local, shared, and platform responsibilities.

3. 1.3 · Choose from constraints6 min

   Turn offline access, data protection, response time, and cost into a short decision record.

Know where a feature belongs and how to change it without pulling apart the whole app.

1. 2.1 · Trace a feature through its layers8 min

   Follow a create-record action through input, access checks, business behavior, and saving.

2. 2.2 · Move business rules out of screens8 min

   Change a business rule independently of the screen that displays its result.

3. 2.3 · Organize around capabilities8 min

   Map module dependencies and identify a call that crosses the wrong boundary.

4. 2.4 · Reuse without overengineering6 min

   Compare shared packages and app configuration. Remove wrappers with no clear purpose.

Define ownership, enforce permissions, and preserve business rules when requests overlap.

1. 3.1 · Entities and ownership8 min

   Map accounts, workspaces, members, and records; scope data to the right owner.

2. 3.2 · Valid states and transitions7 min

   Model draft, scheduled, published, and cancelled announcements; reject contradictory states.

3. 3.3 · Transactions and concurrent writes8 min

   Interrupt related writes and replay concurrent requests to expose consistency problems.

4. 3.4 · Trusted access boundaries7 min

   Review server authorization, secrets, and the difference between identifying a user and permitting an action.

Keep vendors replaceable and distinguish screen state, cached data, and authoritative records.

1. 4.1 · Define an integration contract8 min

   Compare external service providers behind one contract, including capability differences.

2. 4.2 · Choose the source of truth9 min

   Trace local data, API responses, cached reads, and server-controlled writes.

3. 4.3 · Handle stale and failed responses8 min

   Use fakes and account-switch scenarios to check errors, refresh behavior, and stale data.

Plan what happens when an action is retried, duplicated, or only partially completed.

1. 5.1 · Commands, events, and jobs8 min

   Label the different roles in an announcement flow and move slow work off the request path.

2. 5.2 · Retry without duplicating actions10 min

   Replay a request using the same key, then change input to demonstrate conflicts.

3. 5.3 · Persist work that still needs doing12 min

   Step through an outbox, interrupted notification delivery, bounded retries, logs, and recovery.

Separate the paywall from access control and understand the full purchase lifecycle.

1. 6.1 · Checkout, paywall, entitlement8 min

   Draw the boundary between asking for payment and granting a paid capability.

2. 6.2 · Web payments and store purchases9 min

   Compare web and store purchase flows, verification boundaries, and account identity.

3. 6.3 · Renewals, cancellations, and restore10 min

   Walk a state table covering pending payment, renewal, expiry, refund, and restored purchases.

4. 6.4 · Test paid access before launch8 min

   Use fake purchase services and sandbox scenarios to check duplicate events, failed payments, and denied access.

Plan a release that protects existing data and gives you a way to detect and recover from problems.

1. 7.1 · Preserve data through updates10 min

   Examine a failed update that risks deleting saved data; design a migration and recovery path using test data.

2. 7.2 · Release on web, mobile, and desktop10 min

   Compare deployments, signed builds, store review, updates, and coexistence of old and new versions.

3. 7.3 · Check, observe, and recover10 min

   Select checks for access, payment, backups, failure reporting, and recovery. Build a release checklist.

Leave with a system map, a constrained change plan, and a launch-readiness review.

1. 8.1 · Map the actual implementation8 min

   Ask for real files, call paths, owners, and tests; reconcile documentation with code.

2. 8.2 · Challenge a flawed product plan10 min

   Review a deliberately flawed paid-feature plan for authorization, delivery, and lifecycle gaps.

3. 8.3 · Write constraints AI can act on10 min

   Improve the plan with explicit state, entitlements, dependencies, and acceptance checks.

4. 8.4 · Run your launch review7 min

   Apply the checklist to web, mobile, or desktop and explain unresolved risks before release.