Feynman DSL Documentation

Overview

Feynman is a domain-specific language (DSL) for creating animated sequence diagrams. It allows you to describe complex system interactions in a simple, readable format.

🎯 Step-by-Step Animation

Break down complex flows into individual steps that viewers can navigate through

🔄 Hierarchical Sequences

Compose diagrams from reusable subsystems for better organization

🎨 Visual Directives

Focus, dim, show, and hide participants to guide viewer attention

📦 Activation Boxes

Show when participants are actively processing

📝 Notes & Annotations

Add explanatory text and documentation directly to your diagrams

Basic Syntax

Every Feynman diagram starts with an animateSequence declaration:

animateSequence "My Diagram Title"
  participant Client
  participant Server

  step "Description of what happens"
    Client -> Server: "Request message"
  end
end

Note: All blocks must be properly closed with end keywords.

Participants

Participants are the actors in your sequence diagram. They can be services, users, databases, or any entity that sends or receives messages.

Basic Participant

participant UserService

Subsystem Participant

Reference a previously defined sequence as a subsystem using the * prefix:

participant *authService

Example: Multiple Participants

animateSequence "API Gateway Flow"
  participant Client
  participant APIGateway
  participant AuthService
  participant Database
end

Steps and Interactions

Steps are the building blocks of your animation. Each step has a description and contains one or more interactions.

Step Syntax

step "Step description"
  From -> To: "Message"
end

Interaction Syntax

Interactions follow the pattern: FromParticipant Arrow ToParticipant: "Message"

Example: Multiple Interactions in a Step

step "User authentication flow"
  Client -> APIGateway: "POST /login"
  APIGateway -> AuthService: "Verify credentials"
  AuthService -> Database: "SELECT user"
  Database --> AuthService: "User data"
  AuthService --> APIGateway: "JWT token"
  APIGateway --> Client: "200 OK"
end

Self-Interactions

A participant can interact with itself, shown as a loop:

Validator -> Validator: "Parse JWT"

Arrow Types

Different arrow types convey different meanings in your diagram:

-> Solid arrow for synchronous calls

--> Dashed arrow for return/response messages

->> Async arrow for asynchronous operations

-->> Dashed async arrow for async responses

Example: Different Arrow Types

step "Mixed interaction types"
  Client -> Server: "Synchronous request"
  Server --> Client: "Synchronous response"
  Server ->> MessageQueue: "Publish event (async)"
  MessageQueue -->> Worker: "Event delivered (async)"
end

Directives

Directives control participant visibility and help guide viewer attention through your diagram.

Directive	Effect	Use Case
`focus:`	Highlights specified participants	Draw attention to active components
`dim:`	Fades specified participants	De-emphasize inactive components
`show:`	Makes participants visible	Introduce new components
`hide:`	Makes participants invisible	Remove components from view
`activate:`	Shows activation box on lifeline	Indicate active processing
`deactivate:`	Removes activation box	End processing state

Directive Syntax

Directives are placed at the beginning of a step and can target multiple participants:

step "Focus on authentication"
  focus: Client, AuthService
  dim: Database
  Client -> AuthService: "Authenticate"
end

Example: Using Directives

animateSequence "Progressive Reveal"
  participant A
  participant B
  participant C

  step "Introduce A"
    show: A
    dim: B, C
  end

  step "A calls B"
    focus: A, B
    dim: C
    A -> B: "Request"
  end

  step "B calls C"
    focus: B, C
    dim: A
    B -> C: "Forward"
  end
end

Hierarchical Sequences

Build complex diagrams by composing smaller sequences into larger ones. This promotes reusability and keeps diagrams organized.

Defining a Subsystem

Use &identifier to assign a reference name to a sequence:

animateSequence "Auth Service" &authService
  participant TokenValidator
  participant SessionStore

  step "Validate token"
    TokenValidator -> SessionStore: "Check session"
  end
end

Using a Subsystem

Reference the subsystem in another sequence using *identifier:

animateSequence "Main Flow"
  participant Client
  participant *authService

  step "Client authenticates"
    Client -> *authService: "Login request"
  end
end

Example: Complete Hierarchical System

# Define subsystems first
animateSequence "Database Layer" &dbLayer
  participant Cache
  participant Database

  step "Cache lookup"
    Cache -> Database: "Query if miss"
  end
end

animateSequence "Auth Layer" &authLayer
  participant Validator
  participant SessionStore

  step "Validate"
    Validator -> SessionStore: "Check session"
  end
end

# Use subsystems in main flow
animateSequence "Application Flow"
  participant Client
  participant API
  participant *authLayer
  participant *dbLayer

  step "Client request"
    Client -> API: "Request"
  end

  step "Authenticate"
    API -> *authLayer: "Verify"
  end

  step "Fetch data"
    API -> *dbLayer: "Query"
  end
end

Activation Boxes

Activation boxes appear on a participant's lifeline to show when they are actively processing.

Using Activation

step "Processing starts"
  activate: Server
  Client -> Server: "Request"
end

step "Processing continues"
  Server -> Database: "Query"
end

step "Processing ends"
  Server -> Client: "Response"
  deactivate: Server
end

Tip: Activation boxes persist across steps until explicitly deactivated, showing the full duration of processing.

Example: Nested Activations

animateSequence "Request Processing"
  participant Client
  participant Server
  participant Database

  step "Request arrives"
    activate: Server
    Client -> Server: "GET /users"
  end

  step "Server queries database"
    activate: Database
    Server -> Database: "SELECT * FROM users"
  end

  step "Database returns"
    Database --> Server: "User records"
    deactivate: Database
  end

  step "Server responds"
    Server --> Client: "200 OK"
    deactivate: Server
  end
end

Notes & Annotations

Notes allow you to add explanatory text or annotations to your diagrams. They appear as colored boxes positioned relative to participants.

Note Syntax

Notes can be positioned in three ways:

note over: Participant: "Note text"      # Over a participant
note left: Participant: "Note text"     # To the left
note right: Participant: "Note text"    # To the right

Notes Spanning Multiple Participants

For "over" positioning, you can span a note across multiple participants:

note over: Participant1, Participant2: "Spans both participants"

Tip: Notes appear in the order they're defined within a step and are shown/hidden as you navigate through the animation.

Example: Using Notes

animateSequence "Authentication with Notes"
  participant Client
  participant Server
  participant Database

  step "Login attempt"
    note over: Client: "User enters credentials"
    Client -> Server: "POST /login"
  end

  step "Verify credentials"
    activate: Server
    note over: Server, Database: "Check against stored hash"
    Server -> Database: "SELECT password_hash"
    Database --> Server: "Hash returned"
  end

  step "Generate token"
    Server -> Server: "Create JWT"
    note over: Server: "Token valid for 24 hours"
    Server --> Client: "200 OK + token"
    deactivate: Server
  end
end

Example: Notes with Subsystems

animateSequence "Payment Processing"
  participant Client
  participant *paymentService
  participant Bank

  step "Process payment"
    Client -> *paymentService: "Charge card"
    note over: *paymentService: "Subsystem handles PCI compliance"
  end

  step "Bank authorization"
    *paymentService -> Bank: "Authorize transaction"
    note left: Bank: "External API call"
    Bank --> *paymentService: "Approved"
  end
end

Note Positioning Guidelines

over: Best for general annotations about what's happening
left/right: Useful for side comments or when diagram is crowded
Spanning notes: Great for highlighting interactions between specific participants

Complete Examples

Example 1: Simple API Call

animateSequence "Simple REST API"
  participant Browser
  participant API
  participant Database

  step "User requests data"
    Browser -> API: "GET /api/users"
  end

  step "API queries database"
    activate: API
    API -> Database: "SELECT * FROM users"
    Database --> API: "User records"
  end

  step "API returns response"
    API --> Browser: "200 OK [users]"
    deactivate: API
  end
end

Example 2: Authentication Flow with Caching

animateSequence "Auth with Cache"
  participant Client
  participant Server
  participant Cache
  participant Database

  step "Login attempt"
    Client -> Server: "POST /login"
    activate: Server
  end

  step "Check cache for user"
    Server -> Cache: "GET user:email"
    Cache --> Server: "Cache miss"
  end

  step "Query database"
    dim: Cache
    focus: Server, Database
    activate: Database
    Server -> Database: "SELECT FROM users"
    Database --> Server: "User data"
    deactivate: Database
  end

  step "Update cache"
    focus: Server, Cache
    Server ->> Cache: "SET user:email (async)"
  end

  step "Return to client"
    focus: Server, Client
    Server --> Client: "200 OK + JWT"
    deactivate: Server
  end
end

Example 3: Microservices with Subsystems

# Payment processing subsystem
animateSequence "Payment Service" &paymentService
  participant Gateway
  participant Processor
  participant Bank

  step "Process payment"
    activate: Processor
    Gateway -> Processor: "Charge card"
    Processor -> Bank: "Authorize"
    Bank --> Processor: "Approved"
    Processor --> Gateway: "Success"
    deactivate: Processor
  end
end

# Order management subsystem
animateSequence "Order Service" &orderService
  participant OrderAPI
  participant Inventory
  participant Database

  step "Create order"
    activate: OrderAPI
    OrderAPI -> Inventory: "Check stock"
    Inventory --> OrderAPI: "Available"
    OrderAPI -> Database: "INSERT order"
    deactivate: OrderAPI
  end
end

# Main e-commerce flow
animateSequence "Checkout Flow"
  participant Customer
  participant WebApp
  participant *orderService
  participant *paymentService
  participant Email

  step "Checkout initiated"
    Customer -> WebApp: "Click checkout"
  end

  step "Create order"
    activate: WebApp
    WebApp -> *orderService: "Create order"
    *orderService --> WebApp: "Order ID"
  end

  step "Process payment"
    WebApp -> *paymentService: "Charge customer"
    *paymentService --> WebApp: "Payment confirmed"
  end

  step "Send confirmation"
    WebApp ->> Email: "Send receipt (async)"
    WebApp --> Customer: "Order complete"
    deactivate: WebApp
  end
end

Tips and Best Practices

Use descriptive step descriptions: They appear in the UI and help viewers understand the flow
Keep steps focused: Each step should represent one logical action or phase
Use directives strategically: Guide attention to the most important parts of each step
Leverage hierarchical sequences: Break complex systems into reusable subsystems
Match arrow types to semantics: Use solid for sync calls, dashed for returns, async for fire-and-forget
Show activation duration: Use activate/deactivate to clearly show processing spans
Add notes for clarity: Use notes to explain complex logic, highlight important decisions, or document assumptions
Comment your code: Use # for single-line comments to document your diagrams