Visitors
Define hierarchical capability trees and user journeys for actors interacting with your system.
Keywords
visitor- Define a visitor/user/actorcan- Define capability (in visitor context)- Nested blocks represent state transitions and capability scopes
visitor Keyword
The visitor construct defines what actions a user or actor can perform, organized in a hierarchical tree structure with nested capabilities and state transitions.
Syntax
visitor {
can action
can action {
state_name {
can nested_action
}
}
}
Key Features
- Hierarchical capabilities - Nest actions within actions
- State transitions - Named blocks represent state changes
- Scope management - Inner capabilities only available in certain contexts
- User journey mapping - Model complete user flows
Basic Examples
Simple Visitor
visitor {
can browse products
can view product details
can search
}
Visitor with State Transition
visitor {
can browse
can login {
logged in {
can view profile
can view orders
can logout
}
}
}
Nested Capabilities
visitor {
can browse {
browsing {
can search products
can filter by category
can sort results
can view details {
viewing_product {
can add to cart
can read reviews
can share
}
}
}
}
}
Advanced Patterns
E-Commerce User Journey
visitor {
# Anonymous user capabilities
can view landing page
can browse products
can search
can view product details
# Registration flow
can register {
registering {
can fill form
can verify email
}
}
# Authentication flow
can login {
logged in {
# Shopping capabilities
can add to cart
can view cart
can checkout {
checking out {
can enter shipping info
can select payment method
can apply coupon
can place order
}
}
# Account management
can manage profile {
can update email
can change password
can set preferences
}
# Order management
can view orders {
can view order details
can track shipment
can request refund
}
can logout
}
}
}
Content Platform
visitor {
can see landing page
can browse content
can search articles
can login {
logged in {
can read premium content
can save bookmarks
can leave comments
can create content {
creating {
can write article
can upload images
can preview
can publish
}
}
can manage profile {
can update bio
can change avatar
can view statistics
}
}
}
can subscribe {
subscribed {
can access premium features
can download content
can attend webinars
}
}
}
Todo Application
visitor {
can see landing page
can see docs {
can see instructions
can see examples
}
can register
can login {
logged in {
can list todo tables
can create todo table
can enter todo table {
can add new todo
can edit todo
can mark todo done
can mark todo undone
can delete todo
can filter todos
can sort todos
}
can manage account {
can update profile
can change password
can delete account
}
can logout
}
}
}
Understanding Visitor Structure
Capability Levels
Visitors support deep nesting to represent different scopes:
visitor {
# Level 1: Public capabilities
can browse
# Level 2: Action with context
can login {
# Level 3: State after login
logged in {
# Level 4: Capabilities in logged-in state
can view dashboard
# Level 5: Nested action
can manage settings {
# Level 6: Settings context
managing_settings {
# Level 7: Specific settings actions
can update preferences
}
}
}
}
}
State Blocks
Named blocks (like logged in, browsing) represent states or contexts:
visitor {
can login {
logged in { # State: user is authenticated
can view account # Only available when logged in
}
}
can shop {
shopping { # State: user is shopping
can add to cart # Only available while shopping
}
}
}
Best Practices
Naming Conventions
-
Action names: Use verb phrases
can browse productscan view detailscan place order
-
State names: Use present tense or adjectives
logged inbrowsingchecking out
Organization
- Group related capabilities together
- Limit nesting depth to 4-6 levels for readability
- Use consistent state names across your app
- Start with public capabilities then authenticated ones
Example Structure
visitor {
# Public capabilities first
can view public_page
can browse public_content
# Authentication flows
can login { ... }
can register { ... }
# Authenticated capabilities
can login {
logged in {
# Core features
can use_feature_a
can use_feature_b
# Account management
can manage_account { ... }
# Exit
can logout
}
}
}
Integration with Other Constructs
With Roles
role CustomerRole {
permission products {
read
}
permission orders {
create,
read
}
}
visitor {
can login {
logged in {
# Implicitly has CustomerRole permissions
can browse products
can place order
can view orders
}
}
}
With Workflows
workflow OrderFlow {
state cart -> checkout
state checkout -> payment
state payment -> confirmed
}
visitor {
can shop {
shopping {
can add to cart # -> cart state
can checkout { # -> checkout state
checking_out {
can pay # -> payment state
}
}
}
}
}
With Agents
agent OrderProcessor {
can process order when submitted
can send confirmation
}
visitor {
can place order {
# Triggers OrderProcessor agent
}
}
Complete Examples
Social Media Platform
visitor {
can view feed
can view profiles
can search users
can register {
registering {
can fill profile
can upload avatar
can verify email
}
}
can login {
logged in {
can create post {
posting {
can write text
can upload media
can add tags
can publish
}
}
can interact {
can like posts
can comment
can share
can follow users
}
can manage content {
can edit posts
can delete posts
can view analytics
}
can manage account {
can update profile
can change privacy
can block users
}
}
}
}
Project Management Tool
visitor {
can view landing
can see pricing
can signup {
signing_up {
can choose plan
can enter details
can verify
}
}
can login {
logged in {
can list projects
can create project {
can set name
can add members
can configure
}
can enter project {
in_project {
can view board
can create task
can edit task
can assign task
can comment
can manage project {
can edit settings
can invite members
can view reports
}
}
}
can manage workspace {
can view billing
can manage users
can configure integrations
}
}
}
}
Common Patterns
Anonymous + Authenticated
visitor {
# Anonymous
can browse
can search
# Authenticated
can login {
logged in {
can create
can edit
can delete
}
}
}
Multi-Step Process
visitor {
can start_process {
step1 {
can complete_step1 {
step2 {
can complete_step2 {
step3 {
can finish
}
}
}
}
}
}
}
Role-Based Access
visitor {
can login {
logged in {
can access_user_features
# Admin-only
can access_admin {
admin_mode {
can manage_users
can view_analytics
can configure_system
}
}
}
}
}
Related Keywords
role- Define permissions for visitorsworkflow- Model state transitionsagent- Process visitor actions
Next Steps
- Learn about Roles & Permissions
- Explore Workflows for state management
- See Complete Examples with visitor definitions