DevelopmentWorkflows
Workflows Documentation
Workflows Documentation
Overview
The SuitsBooks workflow system is built on top of Worlds Engine by XYLEX Group, providing a robust, scalable solution for executing asynchronous, multi-step processes. Workflows enable you to orchestrate complex business logic with automatic retries, error handling, and execution tracking.
Key Features
- Reliable Execution: Automatic retries and error handling for failed steps
- Async Processing: Long-running tasks don't block your API
- Execution Tracking: Monitor workflow runs and step attempts in real-time
- Scalable: Worker-based architecture supports high concurrency
- Type-Safe: Full TypeScript support with type-checked inputs and outputs
- Database-Backed: All workflow state persisted in PostgreSQL
Quick Start
1. Start the Worker
The worker processes workflow executions. Start it with:
# From the root directory
tsx workflows/worker.ts
```typescript
Or use the npm script (if configured):
```bash
pnpm workflow:worker
```typescript
### 2. Trigger a Workflow via API
```bash
POST /api/workflow/send-email-received-ein
Content-Type: application/json
{
"userId": "user-123",
"companyId": "company-456",
"organizationId": "org-789",
"email_action": "sf_formations_we_received_your_ein",
"recipient_name": "John Doe",
"recipients": ["john@example.com"],
"resource_id_ref": "resource-uuid",
"ccs": []
}
```typescript
### 3. Check Workflow Status
```bash
GET /api/workflow/send-email-received-ein?runId=run-123
```typescript
## Available Workflows
### `send-welcome-email`
Sends a welcome email to a new user and marks it as sent in the database.
**Input:**
```typescript
{
userId: string;
}
```typescript
**Steps:**
1. Fetches user from database
2. Sends welcome email
3. Marks `welcomeEmailSent` flag in database
### `send-email-received-ein`
Sends an email notification about receiving an EIN (Employer Identification Number).
**Input:**
```typescript
{
userId: string;
companyId: string;
organizationId: string;
emailAction: string;
recipientName?: string;
recipients: string[];
resource_id_ref?: string;
ccs?: string[];
}
```typescript
**Steps:**
1. Sends email via mail-v2 API
## Documentation Structure
- **[Architecture](./architecture.md)** - System design and components
- **[API Usage](./api-usage.md)** - Complete API reference
- **[Creating Workflows](./creating-workflows.md)** - Guide to building new workflows
- **[Worker Setup](./worker-setup.md)** - Worker configuration and deployment
- **[Examples](./examples.md)** - Code examples and use cases
## Prerequisites
- PostgreSQL database with `DATABASE_URL` environment variable set
- Worlds Engine schema initialized (see `workflows/schema.sql`)
- Node.js runtime environment
## Next Steps
- Read [Architecture](./architecture.md) to understand how the system works
- Check [API Usage](./api-usage.md) for detailed API documentation
- Follow [Creating Workflows](./creating-workflows.md) to build your first workflow