Coding

Create a detailed sequence diagram in Mermaid syntax that precisely models an API flow including request/response payloads, authentication, error handling, and asynchronous operations.

SEQUENCE DIAGRAM PROCESS:

1. Flow Analysis
   - Identify all actors and services that participate in the flow (user, browser, API gateway, microservices, databases, external APIs)
   - Determine the trigger event that initiates the flow
   - Map the complete happy path from initiation to final response
   - Identify all branching points: conditionals, error paths, retry logic
   - Determine which operations are synchronous vs. asynchronous (fire-and-forget, event-driven, webhook callbacks)

2. Authentication and Authorization Modeling
   - Show token acquisition or session establishment if it is part of this flow
   - Show where tokens are validated and by which service
   - Model token refresh flows if applicable
   - Show authorization checks (role verification, permission checks) at the appropriate service boundary
   - Indicate what happens when auth fails (401/403 responses)

3. Payload Design
   - Include simplified but realistic request payloads at each service boundary (not every internal call)
   - Show response payloads for both success and error cases
   - Include HTTP status codes with each response arrow
   - Show headers that are architecturally significant (Authorization, Content-Type, correlation IDs)

4. Error Path Modeling
   - Model at least the 2-3 most important error scenarios as alt blocks
   - Show error propagation: how an error in a downstream service surfaces to the caller
   - Include timeout handling and retry logic if applicable
   - Show compensation or rollback actions for failed multi-step operations
   - Model circuit breaker behavior if relevant

5. Asynchronous Operations
   - Distinguish sync calls (solid arrows) from async events (dashed arrows) using Mermaid syntax
   - Show message queues or event buses as explicit participants
   - Model callback or webhook flows with clear temporal ordering
   - Show parallel operations using par blocks where applicable
   - Indicate background jobs or scheduled tasks triggered by the flow

6. Diagram Quality
   - Use activate/deactivate to show when each participant is processing
   - Add notes for complex business logic that cannot be expressed as simple messages
   - Use loop, alt, opt, and par blocks to model control flow clearly
   - Keep message labels concise but precise (include HTTP method and path for API calls)

OUTPUT CONSTRAINTS:
- Produce valid Mermaid sequence diagram syntax that renders without errors
- Include at minimum: the happy path AND one error/alternate path
- Every message arrow must have a descriptive label
- Payloads should be simplified to key fields only (3-5 fields), not full schemas
- If information about error handling or auth is not provided, include reasonable defaults and mark with [ASSUMED]
- Add a written description of the flow below the diagram for context

FORMAT:
## Sequence Diagram: [Flow Name]

### Overview
[1-2 paragraph description of the flow, when it is triggered, and its outcome]

### Diagram
```mermaid
sequenceDiagram
    [complete diagram code]
```

### Flow Description
[Step-by-step numbered walkthrough of the happy path]

### Error Scenarios
[Description of each error path shown in the diagram and how it is handled]

### Payloads Reference
[Table or JSON blocks showing the full request/response schemas for key interactions]

### Notes
[Assumptions, edge cases, or design decisions worth documenting]

---

MY INFO:

Flow Name (e.g., "User Authentication" or "Order Processing"): (required)

Actors/Services Involved: (required)
1.
2.
3.
4.

Step-by-Step Flow: (required)
1.
2.
3.

Authentication Mechanism (JWT, OAuth2, API key, session): (optional)

Known Error Scenarios to Include: (optional)

Asynchronous Operations (background jobs, events, webhooks): (optional)

Protocol Details (REST, gRPC, GraphQL, WebSocket): (optional)