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: Syntax and use cases for eq, neq, exists, etc.
• Complex Flow Recipes: 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.

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.