[Flow Name] User Flow

Status: Draft Last Updated: YYYY-MM-DD Owner: Product / Engineering

Purpose

This document defines the user flow for [Flow Name].

It describes:

  • The sequence of user actions
  • Page-by-page UI structure
  • System behavior and decision points
  • Error and blocked states

This document defines how users experience the system. Business rules and invariants are defined in specs and contracts.

Scope

In Scope

  • [User-visible steps]
  • [Pages and transitions]
  • [Success and failure paths]

Out of Scope

  • [Deferred flows]
  • [Background-only behavior]
  • [Implementation details]

Preconditions

The flow assumes:

  • Authentication state: [logged out / logged in]
  • User role: [user / admin]
  • Subscription tier (if applicable)
  • Required existing data (if any)

Authorization MUST comply with:

  • docs/contracts/authz-and-roles.new.md
  • docs/contracts/rls-standard.new.md

Entry Points

Users may enter this flow from:

  • Route: /path
  • CTA: [Button label]
  • Deep link or notification (if applicable)

High-Level Flow Overview (ASCII)

[ Entry Point ] | v [ Page A ] | +--> [ Blocked State ] | v [ Page B ] | v [ Success State ]

This diagram shows the happy path plus the primary diversion only. Edge cases are detailed below.

Page-by-Page Flow

Page 1: [Page Name]

Route: /path/to/page

Purpose

What the user is trying to accomplish on this page.

UI Layout (ASCII)

+--------------------------------------------------+ | Header | | - Logo | | - Navigation | +--------------------------------------------------+ | | | Page Title | | Short explanation of what this page does | | | | [ Primary Input Field ] | | | | [ Secondary Option ] |
[ Primary CTA Button ]
[ Secondary CTA ]
+--------------------------------------------------+

UI Elements

  • Header:
    • [List elements]
  • Inputs:
    • [Input name] — purpose
  • CTAs:
    • Primary: [label]
    • Secondary: [label]
  • System indicators:
    • Loading state
    • Error state
    • Disabled state

User Actions

Action Result
Click Primary CTA Validate input and proceed
Click Secondary CTA Navigate elsewhere

System Behavior

On primary action:

  • Server validates request
  • Authorization checked
  • Data read or write occurs
  • Errors returned if any

All data access MUST comply with RLS.

States

  • Loading:
    • CTA disabled
    • Spinner or progress indicator
  • Error:
    • Inline message
    • No sensitive details exposed
  • Blocked:
    • Clear explanation
    • Next steps if available

Data Interaction

  • Reads:
    • [Table name] — purpose
  • Writes:
    • [Table name] — purpose

Transition Conditions

Condition Next Page
Success Page 2
Validation failure Stay on Page 1
Authorization failure Blocked State

Page 2: [Page Name]

Route: /path/to/page-2

Repeat the same structure as Page 1.

Blocked and Error States

Blocked State: [Reason]

Displayed when:

  • [Condition]

UI Layout (ASCII)

+--------------------------------------------------+ | ❌ Action Not Available | | | | Explanation of why the action is blocked | | | | [ Optional CTA: Fix Issue / Upgrade / Contact ] | +--------------------------------------------------+

Behavior:

  • No partial side effects
  • Action cannot proceed
  • State is logged for observability

Alternate Paths

Alternate Path A: [Description]

Trigger:

  • [Condition]

Flow:

[ Page A ] | v [ Alternate Page ] | v [ Return or Exit ]

Success State

Final Success Page or State

Purpose:

  • Confirm completion
  • Provide next steps

UI Layout (ASCII)

+--------------------------------------------------+ | ✅ Success | | | | Confirmation message | | | | [ Next Action CTA ] | | [ Return to Dashboard ] | +--------------------------------------------------+

Error Handling Summary

Error Type User Message Recovery
Validation Fix input Retry
Rate limit Try later Wait
Permission Not allowed None
System Temporary issue Retry

Errors MUST be logged and observable.

Observability Notes

This flow MUST emit:

  • Page view events
  • Action attempt events
  • Success and failure outcomes
  • Blocked state occurrences

Observability MUST comply with:

  • docs/architecture/observability-plan.new.md

Non-Negotiable Rules

  • UI gating is advisory only
  • Server enforces all rules
  • RLS prevents cross-user access
  • Blocked states are explicit
  • Partial completion is not allowed

Acceptance Criteria

  • All pages render correctly
  • Transitions match this flow
  • Blocked states behave as documented
  • No contract violations
  • Observability present

References

  • docs/governance/doc-authority.new.md
  • docs/contracts/authz-and-roles.new.md
  • docs/contracts/rls-standard.new.md
  • docs/contracts/rate-limits-and-abuse.new.md
  • docs/architecture/system-overview.new.md

End of Document