# User Flow TOML Schema

## Overview
This document defines the TOML schema used for all user flows in the Invoico project. Using TOML ensures flows are both human-readable and easily parseable by AI agents and automation tools.

## TOML Schema Structure

### Flow Definition
```toml
[flow]
id = "unique_flow_identifier"
name = "Human Readable Flow Name"
type = "atomic" # or "composed"
actor = "user_type"
trigger = "what initiates the flow"
description = "brief description of the flow"

[flow.user_story]
story_id = "US001" # or "DEV001", "API001", etc.
story_title = "Human readable story title"
story_document = "freelancer-stories.md" # or "developer-stories.md", "api-customer-stories.md"

[flow.dependencies]
systems = ["required_systems"]
states = ["required_states"]
prerequisites = ["required_conditions"]

[flow.success_criteria]
primary = "main success condition"
secondary = ["additional success conditions"]

[flow.error_handling]
"error_condition" = "how to handle this error"

[flow.metrics]
time_target = "expected completion time"
success_rate_target = "expected success percentage"

# For atomic flows
[[flow.steps]]
order = 1
action = "description of step"
actor = "who performs this step"
system_interaction = "optional system component"
validation = "optional validation check"

# For composed flows
[[flow.composed_steps]]
order = 1
phase = "phase name"
atomic_flows = ["list_of_atomic_flow_ids"]
description = "what happens in this phase"
```

### Integration Points
```toml
[integrations]
systems = ["list_of_integrated_systems"]
apis = ["api_endpoints_used"]
notifications = ["notification_channels"]
```

### Business Rules
```toml
[business_rules]
constraints = ["business_constraints"]
validations = ["validation_rules"]
permissions = ["required_permissions"]
```

## Example Flow in TOML Format

```toml
[flow]
id = "create_new_client"
name = "Create New Client"
type = "atomic"
actor = "freelancer"
trigger = "new client relationship begins"
description = "Freelancer adds a new client to the system with all required information"

[flow.user_story]
story_id = "US201"
story_title = "Client Information Management"
story_document = "freelancer-stories.md"

[flow.dependencies]
systems = ["user_management", "client_database"]
states = ["user_authenticated", "valid_subscription"]
prerequisites = ["freelancer_account_active"]

[flow.success_criteria]
primary = "client is created and appears in client list"
secondary = [
    "client information is saved correctly",
    "freelancer can view client details",
    "client receives welcome email if opted"
]

[flow.error_handling]
"invalid_email" = "system shows validation error and highlights email field"
"duplicate_client" = "system suggests existing client and offers to update"
"missing_required_fields" = "system highlights missing information with clear messages"
"network_error" = "system saves draft locally and offers retry when connection restored"

[flow.metrics]
time_target = "2 minutes"
success_rate_target = "98%"

[[flow.steps]]
order = 1
action = "Navigate to Clients section"
actor = "freelancer"
system_interaction = "client_management_ui"

[[flow.steps]]
order = 2
action = "Click Add New Client button"
actor = "freelancer"
system_interaction = "client_form_modal"

[[flow.steps]]
order = 3
action = "Fill out client form with company name, contact person, email, phone"
actor = "freelancer"
system_interaction = "client_form_fields"
validation = "email format validation, required fields check"

[[flow.steps]]
order = 4
action = "Enter billing address and payment terms"
actor = "freelancer"
system_interaction = "address_form, payment_terms_dropdown"

[[flow.steps]]
order = 5
action = "Set default hourly rate (optional)"
actor = "freelancer"
system_interaction = "rate_input_field"
validation = "positive number validation"

[[flow.steps]]
order = 6
action = "Save client information"
actor = "freelancer"
system_interaction = "client_database, validation_engine"

[[flow.steps]]
order = 7
action = "System generates unique client ID and confirms creation"
actor = "system"
system_interaction = "id_generator, notification_system"

[integrations]
systems = ["client_database", "email_service", "validation_engine"]
apis = ["/api/v1/clients", "/api/v1/notifications"]
notifications = ["success_toast", "welcome_email"]

[business_rules]
constraints = [
    "email must be unique per freelancer account",
    "payment terms must be from predefined list",
    "hourly rate must be positive if provided"
]
validations = [
    "email format validation",
    "required field validation",
    "phone number format validation"
]
permissions = ["client.create", "client.read"]
```

## Benefits of TOML Format

### For AI Agents
- **Structured parsing**: Easy to extract specific flow components
- **Validation**: Can validate flow completeness and consistency
- **Cross-referencing**: Can identify dependencies between flows
- **Test generation**: Can automatically generate test cases from steps

### For Developers
- **Clear structure**: Consistent format across all flows
- **Searchable**: Easy to grep for specific flows or components
- **Validation**: Can validate flow syntax before committing
- **Documentation**: Self-documenting with clear field meanings

### For Project Management
- **Metrics tracking**: Built-in success criteria and targets
- **Dependency mapping**: Clear prerequisites and system requirements
- **Error planning**: Predefined error handling strategies
- **Integration planning**: Clear system integration requirements

## Validation Rules

### Required Fields
- `flow.id`: Must be unique across all flows
- `flow.name`: Human-readable name
- `flow.type`: Must be "atomic" or "composed"
- `flow.actor`: Must be valid actor type
- `flow.trigger`: Must describe clear trigger condition
- `flow.user_story.story_id`: Must reference valid user story ID
- `flow.user_story.story_document`: Must be valid story document filename

### Optional Fields
- `flow.description`: Recommended for complex flows
- `flow.dependencies`: Should list actual system dependencies
- `flow.success_criteria`: Should define measurable success
- `flow.error_handling`: Should cover common error scenarios
- `flow.metrics`: Should include realistic targets

### Consistency Rules
- All referenced `atomic_flows` in composed flows must exist
- All `systems` in integrations must be defined in system architecture
- All `permissions` must be defined in security model
- Step `order` numbers must be sequential within a flow
- All `story_id` references must exist in the specified `story_document`
- `story_document` must be one of: freelancer-stories.md, developer-stories.md, api-customer-stories.md

### Cross-Reference Validation
- **User Story Mapping**: Each flow must map to exactly one user story
- **Flow Coverage**: Each user story should have at least one corresponding flow
- **Actor Consistency**: Flow actor must match user story actor type
- **Acceptance Criteria Alignment**: Flow success criteria should align with story acceptance criteria

This schema ensures our flows are both human-readable and machine-processable, enabling automated testing, validation, and cross-referencing across the entire system.