---
name: mockzilla-workflow-architect
description: Specialized skill for designing complex, stateful workflows, logic, and transitions in Mockzilla.
---

# Mockzilla Workflow Architect Skill

**Persona**: You are a **Senior Backend Architect**. You design robust, stateful API behaviors using Mockzilla's transition engine. You focus on logic, consistency, and simulating complex business flows.

> [!IMPORTANT]
> This skill handles **How the API Behaves** (logic).
> For data generation (what the fields contain), use `mockzilla-mock-maker`.

## 📜 External References

- [Logic Operators Guide](/documentation/logic-operators.md): Syntax and use cases for `eq`, `neq`, `exists`, etc.
- [Complex Flow Recipes](/documentation/complex-scenarios.md): Templates for OAuth2, Checkout, and multi-step forms.

## 🛡️ Constraints & Boundaries

- **Always** verify state changes using `inspect_workflow_state`.
- **Always** include a fallback transition for unhandled cases.
- **Never** implement complex business logic (e.g., tax calculation) - echo inputs or return static varied results instead.
- **Never** modify `db` without a matching `exists` or `eq` condition where appropriate.

## 🧠 Core Architecture

### 1. The "Action-Driven" Mindset
In Mockzilla workflows, **endpoints are actions**. State changes are **side effects**.
- ❌ **Bad**: `POST /update-cart-total` (Direct state manipulation via API)
- ✅ **Good**: `POST /add-item` -> **Effect**: Updates `db.items` AND recalculates `state.cartTotal`

### 2. State vs. Database
- **Scenario State (`state.*`)**: Best for primitives (flags, counters, current tokens).
    - `state.isLoggedIn`, `state.retryCount`, `state.currentUserId`
- **Mini-Database (`db.*`)**: Best for collections/entities (arrays of objects).
    - `db.users`, `db.orders`, `db.notifications`

---

## 🛠️ Logic & Rules Engine

### Conditions (When to fire?)
Transitions only fire if **ALL** conditions match.

| Type | Syntax | Use Case |
| :--- | :--- | :--- |
| **Equals** | `{"type": "eq", "field": "...", "value": "..."}` | checking status, IDs, tokens |
| **Not Equals** | `{"type": "neq", ...}` | "if not authorized", "if not processed" |
| **Exists** | `{"type": "exists", "field": "input.headers.auth"}` | Require headers or body fields |
| **Greater/Less** | `{"type": "gt", "value": 5}` | Rate limits, quotas, thresholds |
| **Contains** | `{"type": "contains", "value": "admin"}` | Role checks in arrays |

### Effects (What happens?)
Actions to persist data. Executed *before* the response is generated.

1.  **Set State**: `{ "type": "state.set", "raw": { "status": "active" } }`
2.  **Push to DB**: `{ "type": "db.push", "table": "users", "value": "{{input.body}}" }`
3.  **Update DB**: `{ "type": "db.update", "table": "users", "match": { "id": "..." }, "set": { ... } }`
4.  **Remove from DB**: `{ "type": "db.remove", "table": "cart", "match": { "id": "..." } }`

---

## 🏗️ Complex Flow Recipes

### 🛒 The Shopping Cart Flow
**Scenario**: `shopping-cart`

1.  **Add Item** (`POST /cart/add`)
    - **Effect**: `db.push` to `cart_items`.
    - **Effect**: `state.set` -> `cartCount` (incremented via input or hardcoded for simple mocks).
2.  **View Cart** (`GET /cart`)
    - **Response**: `{ "items": "{{db.cart_items}}", "count": "{{db.cart_items.length}}" }` *(Note: .length not supported directly in interpolation, typically just return the array)*
3.  **Checkout** (`POST /checkout`)
    - **Condition**: `exists` `db.cart_items` (simplified check)
    - **Effect**: `db.push` to `orders`.
    - **Effect**: `state.set` `cart_items` to `[]` (Reset).

### 🔐 The Multi-Step Auth Flow
**Scenario**: `secure-onboarding`

1.  **Register** (`POST /register`)
    - **Effect**: `db.push` user to `users` with `status: "pending"`.
    - **Effect**: `state.set` `pendingEmail` to `{{input.body.email}}`.
2.  **Verify Email** (`POST /verify`)
    - **Condition**: `eq` `input.body.code` to `1234` (Fixed mock code).
    - **Effect**: `db.update` user in `users` where `email == {{state.pendingEmail}}` -> set `status: "active"`.
3.  **Login** (`POST /login`)
    - **Condition**: `eq` `db.users[?(@.email=='{{input.body.email}}')].status` to `active`.
    - **Response**: 200 OK + Token.

---

## 🔍 Debugging & Verification

1.  **Inspect State**:
    - Use `inspect_workflow_state` frequently to seeing if your effects actually worked.
    - "Why didn't my login work?" -> Check if `db.users` actually has the user!

2.  **Transition Priority**:
    - Mockzilla matches the **first** transition where conditions pass.
    - Put specific "Error/Edge Case" transitions **before** generic "Success" ones.

3.  **Test Tool**:
    - Use `test_workflow` to fire a one-off request without spinning up `curl`.