Visitors
Define hierarchical capability trees and user journeys for actors interacting with your system.
Keywords
visitor- Define a visitor/user/actor- Capabilities can be quoted (
"browse products") or unquoted (browse) - 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
// Unquoted capabilities (single word)
visitor {
browse
search
login {
viewProfile
logout
}
}
// Quoted capabilities (multi-word or with spaces)
visitor {
"browse products"
"view details" {
"add to cart"
}
}
// Mixed syntax
visitor {
browse // unquoted
"view product details" // quoted for multi-word
login {
viewProfile
"manage orders"
}
}
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 {
browse
search
viewDetails
}
Visitor with State Transition
visitor {
browse
login {
logged in {
viewProfile
viewOrders
logout
}
}
}
Nested Capabilities
visitor {
browse {
browsing {
searchProducts
filterByCategory
sortResults
viewDetails {
viewing_product {
addToCart
readReviews
share
}
}
}
}
}
Advanced Patterns
E-Commerce User Journey
visitor {
# Anonymous user capabilities
viewLandingPage
browseProducts
search
viewProductDetails
# Registration flow
register {
registering {
fillForm
verifyEmail
}
}
# Authentication flow
login {
logged in {
# Shopping capabilities
addToCart
viewCart
checkout {
checking out {
enterShippingInfo
selectPaymentMethod
applyCoupon
placeOrder
}
}
# Account management
manageProfile {
updateEmail
changePassword
setPreferences
}
# Order management
viewOrders {
viewOrderDetails
trackShipment
requestRefund
}
logout
}
}
}
Content Platform
visitor {
seeLandingPage
browseContent
searchArticles
login {
logged in {
readPremiumContent
saveBookmarks
leaveComments
createContent {
creating {
writeArticle
uploadImages
preview
publish
}
}
"manage profile" {
"update bio"
"change avatar"
"view statistics"
}
}
}
"subscribe" {
subscribed {
"access premium features"
"download content"
"attend webinars"
}
}
}
Todo Application
visitor {
"see landing page"
"see docs" {
"see instructions"
"see examples"
}
"register"
"login" {
logged in {
"list todo tables"
"create todo table"
"enter todo table" {
"add new todo"
"edit todo"
"mark todo done"
"mark todo undone"
"delete todo"
"filter todos"
"sort todos"
}
"manage account" {
"update profile"
"change password"
"delete account"
}
"logout"
}
}
}
Understanding Visitor Structure
Capability Levels
Visitors support deep nesting to represent different scopes:
visitor {
# Level 1: Public capabilities
"browse"
# Level 2: Action with context
"login" {
# Level 3: State after login
logged in {
# Level 4: Capabilities in logged-in state
"view dashboard"
# Level 5: Nested action
"manage settings" {
# Level 6: Settings context
managing_settings {
# Level 7: Specific settings actions
"update preferences"
}
}
}
}
}
State Blocks
Named blocks (like logged in, browsing) represent states or contexts:
visitor {
"login" {
logged in { # State: user is authenticated
"view account" # Only available when logged in
}
}
"shop" {
shopping { # State: user is shopping
"add to cart" # Only available while shopping
}
}
}
Best Practices
Naming Conventions
-
Action names: Use verb phrases
"browse products""view details""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
"view public_page"
"browse public_content"
# Authentication flows
"login" { ... }
"register" { ... }
# Authenticated capabilities
"login" {
logged in {
# Core features
"use_feature_a"
"use_feature_b"
# Account management
"manage_account" { ... }
# Exit
"logout"
}
}
}
Integration with Other Constructs
With Roles
role CustomerRole {
permission products {
read
}
permission orders {
create,
read
}
}
visitor {
"login" {
logged in {
# Implicitly has CustomerRole permissions
"browse products"
"place order"
"view orders"
}
}
}
With Workflows
workflow OrderFlow {
state cart -> checkout
state checkout -> payment
state payment -> confirmed
}
visitor {
"shop" {
shopping {
"add to cart" # -> cart state
"checkout" { # -> checkout state
checking_out {
"pay" # -> payment state
}
}
}
}
}
With Agents
agent OrderProcessor {
"process order"
"send confirmation"
}
visitor {
"place order" {
# Triggers OrderProcessor agent
}
}
Complete Examples
Social Media Platform
visitor {
"view feed"
"view profiles"
"search users"
"register" {
registering {
"fill profile"
"upload avatar"
"verify email"
}
}
"login" {
logged in {
"create post" {
posting {
"write text"
"upload media"
"add tags"
"publish"
}
}
"interact" {
"like posts"
"comment"
"share"
"follow users"
}
"manage content" {
"edit posts"
"delete posts"
"view analytics"
}
"manage account" {
"update profile"
"change privacy"
"block users"
}
}
}
}
Project Management Tool
visitor {
"view landing"
"see pricing"
"signup" {
signing_up {
"choose plan"
"enter details"
"verify"
}
}
"login" {
logged in {
"list projects"
"create project" {
"set name"
"add members"
"configure"
}
"enter project" {
in_project {
"view board"
"create task"
"edit task"
"assign task"
"comment"
"manage project" {
"edit settings"
"invite members"
"view reports"
}
}
}
"manage workspace" {
"view billing"
"manage users"
"configure integrations"
}
}
}
}
Common Patterns
Anonymous + Authenticated
visitor {
# Anonymous
"browse"
"search"
# Authenticated
"login" {
logged in {
"create"
"edit"
"delete"
}
}
}
Multi-Step Process
visitor {
"start_process" {
step1 {
"complete_step1" {
step2 {
"complete_step2" {
step3 {
"finish"
}
}
}
}
}
}
}
Role-Based Access
visitor {
"login" {
logged in {
"access_user_features"
# Admin-only
"access_admin" {
admin_mode {
"manage_users"
"view_analytics"
"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