# Designing Modules

Module design tools are available in **configure mode** (the default) and **frontend mode**. If you have switched to runtime mode, ask the AI to switch back first.

{% hint style="info" %}
To check or switch your current mode, tell the AI: *"Switch to configure mode."*
{% endhint %}

## How It Works

The AI uses the `design_factsops_workflow` guided prompt to walk you through a structured design conversation. You describe what you need; the AI generates a complete module schema, validates it locally, and creates it in your workspace.

{% stepper %}
{% step %}

### Describe the workflow

Tell the AI what entity you want to manage and who is involved.

> "Design a purchase order approval workflow. Procurement raises POs, the finance manager approves them, and the system auto-closes approved POs after payment confirmation."

Optionally mention your industry for compliance-aware defaults:

> "Design a patient referral workflow for a healthcare clinic."
> {% endstep %}

{% step %}

### Review the design

The AI calls `design_workflow` to generate a scaffolded schema based on your description. It then presents the proposed:

* **Fields** — what information is captured
* **States** — the lifecycle stages (e.g., Draft → Pending Approval → Approved → Closed)
* **Activities** — the actions that move entries between states
* **Flows** — which activities connect which states, and who can perform them

Review the design and ask for changes before proceeding.
{% endstep %}

{% step %}

### Validate and create

The AI calls `validate_design` to check the schema against all FACTSOps rules — locally, before touching the API. If there are errors, they are fixed automatically or flagged for your input.

Once validation passes, the AI calls `create_module` to persist the module to your workspace.
{% endstep %}

{% step %}

### Confirm the result

The AI calls `get_module_schema` to retrieve and display the created module, confirming everything looks correct.
{% endstep %}
{% endstepper %}

## Example Design Conversation

> **You:** Design a leave request approval workflow for an HR team.
>
> **AI:** I'll design this now. Here's a proposed schema:
>
> **Fields:** Employee, Leave Type (Annual/Medical/Unpaid), Start Date, End Date, Total Days, Reason, Supporting Document
>
> **States:** Submitted → Pending Review → Approved / Rejected
>
> **Activities:** Submit (employee), Approve (HR manager), Reject (HR manager), Cancel (employee)
>
> Does this look right, or would you like to add or change anything?
>
> **You:** Add an "Escalate to Director" activity for leave over 14 days.
>
> **AI:** Added. Validating and creating the module now\...

## FACTSOps Design Rules

The AI enforces the **Three Laws of FACTSOps** automatically:

1. **No transition without a form** — every activity that moves an entry must have a form defining what data is collected
2. **No actor without a trail** — every activity logs who did it, when, and why
3. **No automation without escalation** — AI-executed activities must have a confidence threshold; low-confidence actions are flagged for human review rather than auto-transitioning

These rules are validated before the module is created.

<details>

<summary>State color system</summary>

The AI assigns state colors automatically using the FACTSOps color palette:

| Color                | Meaning                           | Example states                    |
| -------------------- | --------------------------------- | --------------------------------- |
| Grey `#5A6070`       | Not started, idle, queued         | Draft, New, Queued                |
| Blue `#2968A8`       | Waiting for action, no urgency    | Pending Review, Awaiting Approval |
| Green `#2A7B50`      | Active work in progress           | In Progress, Processing           |
| Amber `#A07828`      | Deadline approaching, flagged     | Overdue, Flagged                  |
| Red `#C0392B`        | SLA breached, escalation required | Escalated, Breached               |
| Purple `#6B4D91`     | Blocked by external dependency    | On Hold, Blocked                  |
| Dark Green `#1E6B45` | Terminal success                  | Approved, Completed, Closed       |
| Dark Red `#8B2D2D`   | Terminal failure                  | Rejected, Cancelled               |

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://inistate.gitbook.io/home/mcp-integration/designing-modules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.