User Flows

User Flows in Archyl let you document sequences of interactions across your architecture. Visualize how users, data, or requests move through your system.

What Are Flows?

A Flow represents a sequence of steps through your architecture:

• User journeys: Login, checkout, signup
• Data flows: Order processing, data sync
• System interactions: API calls, event chains
• Error handling: Failure scenarios, retries

Each step in a flow references relationships in your architecture, creating a connected view of how things work.

Creating a Flow

From the Flows Tab

1. Go to the Flows tab in your project
2. Click Create Flow
3. Enter a name and description
4. Add steps by selecting relationships
5. Click Save

Flow Structure

Each flow contains:

Adding Steps

For each step:

1. Select a relationship from your architecture
2. The step shows source, target, and relationship label
3. Drag to reorder steps
4. Add notes for additional context

Viewing Flows

Step-by-Step Navigation

When viewing a flow:

• Steps are shown in order
• Current step is highlighted on the diagram
• Navigate with Next/Previous buttons
• See the full context at each step

Animated Playback

Click Play to animate through the flow:

• Automatic step progression
• Highlighted path on diagram
• Adjustable playback speed

Sharing Flows

Public Flow Links

User Flows have built-in public sharing:

1. Open a Flow
2. Click the Share icon
3. Copy the public URL
4. Share with anyone

The public view includes:

• Step-by-step navigation
• Architecture visualization
• Flow description
• No authentication required

Embedding Flows

Embed flows in external tools:

• Confluence
• Notion
• Documentation sites
• Wikis

Best Practices

Name Flows Clearly

Use action-oriented names:

• "User Registration"
• "Order Checkout Process"
• "Payment Refund Flow"
• "Data Sync Pipeline"

Keep Flows Focused

• One flow per user journey
• 5-15 steps is ideal
• Break complex flows into sub-flows
• Reference other flows when needed

Add Context

Use descriptions to explain:

• Why this flow exists
• Who uses it
• When it's triggered
• What the expected outcome is

Link to Documentation

Reference related docs:

• API specifications
• Requirements documents
• ADRs explaining design choices

Example Flows

E-commerce Checkout

1. User → Cart Service: "View cart"
2. Cart Service → Inventory: "Check availability"
3. User → Checkout Service: "Begin checkout"
4. Checkout Service → Payment: "Process payment"
5. Payment → Order Service: "Create order"
6. Order Service → Notification: "Send confirmation"

API Authentication

1. Client → API Gateway: "Request with credentials"
2. API Gateway → Auth Service: "Validate token"
3. Auth Service → User DB: "Lookup user"
4. Auth Service → API Gateway: "Return claims"
5. API Gateway → Backend: "Forward with user context"

Next Steps

• C4 Model Overview - Understand the architecture model
• Relationships - Create relationships for flows
• Sharing - Share flows publicly