> For the complete documentation index, see [llms.txt](https://inistate.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://inistate.gitbook.io/home/mcp-integration/designing-modules.md).

# 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>