> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quixa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture & Hierarchy

> Understand Quixa's 3-tier enterprise architecture: Nodes, Flows, and Flow Suites.

Quixa organizes visual API orchestration, contract testing, and data generation into a structured **3-tier hierarchical architecture**:

```mermaid theme={null}
graph TD
    Suite["Flow Suite (Enterprise Regression / Test Plan)"]
    Suite --> Flow1["Flow 1: User Onboarding & Auth"]
    Suite --> Flow2["Flow 2: Order Fulfillment & Inventory"]
    Suite --> Flow3["Flow 3: Billing & Invoice Dispatch"]

    Flow1 --> Node1["Node: HTTP POST /auth/login"]
    Flow1 --> Node2["Node: Decision Router (IF / Switch)"]
    Flow1 --> Node3["Node: Subflow / Micro-Chain"]
    Flow1 --> Node4["Node: Barrier Join (Collect)"]

    style Suite fill:#6d28d9,stroke:#a78bfa,stroke-width:2px,color:#fff
    style Flow1 fill:#1e1b4b,stroke:#7c3aed,stroke-width:2px,color:#fff
    style Flow2 fill:#1e1b4b,stroke:#7c3aed,stroke-width:2px,color:#fff
    style Flow3 fill:#1e1b4b,stroke:#7c3aed,stroke-width:2px,color:#fff
```

***

## 1. The Atomic Unit: Node

A **Node** is the fundamental atomic building block of any Quixa workflow. Every node performs a discrete action, enforces isolated assertions, and provides structured input and output contracts.

### Types of Nodes

* **HTTP Request Nodes**: Dispatches REST or HTTP requests (GET, POST, PUT, DELETE, PATCH) with automated payload binding, headers, query parameters, and authentication.
* **Control Flow Nodes**: Logic routing components including **If-Condition**, **Switch Router**, **For Loop**, **Repeat Loop**, and **Stop Flow**.
* **Synchronization Nodes**: **Wait / Delay** nodes and **Collect / Barrier Join** nodes for orchestrating parallel asynchronous branches.
* **Code Execution Nodes**: Polyglot sandboxed scripts (**JavaScript**, **TypeScript**, **Python**, **cURL**, **AWS Lambda**).
* **Integration Nodes**: **Webhook** listeners, **Event Triggers**, and **Subflows**.
* **Annotation Nodes**: **Canvas Frames (Groups)**, **Sticky Notes**, and **Free-Format Text Labels** for team collaboration and visual documentation.

### Node Anatomy

Each node encapsulates:

1. **Configurable Inputs**: URL templates, dynamic parameters, request body, and auth schemes.
2. **Variable Extracts**: Rules for pulling values from response bodies or headers into runtime variables.
3. **Polling Rules**: Automated endpoint polling conditions (`continueWhen` and `stopWhen`).
4. **Assertions & Retries**: Automated validation rules against HTTP status codes, latency, headers, and JSON schema with custom retry policies.
5. **Execution Results**: Status codes, latency benchmarks, formatted JSON inspector, and step logs.

***

## 2. The Directed Graph: Flow

A **Flow** is an executable directed graph (DAG or looping pipeline) connecting multiple nodes into an automated end-to-end process.

```mermaid theme={null}
flowchart LR
    A["POST /customers"] --> B["POST /accounts"]
    B --> C{"Check Score (IF)"}
    C -- "Score >= 700" --> D["POST /cards/approve"]
    C -- "Score < 700" --> E["POST /review/queue"]
    D --> F["Collect & Notify"]
    E --> F
```

### Key Capabilities of Flows

* **Dynamic Data Plumbing**: Seamlessly transfers tokens, session IDs, and entity references between nodes via the **Response Binding Engine** (`{{ResponseBinding.<alias>.body.<path>}}`).
* **State & Scope Isolation**: Each flow execution maintains an isolated runtime state, preventing data leaks across concurrent executions.
* **Error Handling & Branching**: Configurable error strategies (`Continue On Error`, `Halt Flow`, `Fallback Path`).
* **Visual Diagnostics**: During execution, active paths highlight in green, while branches skipped by conditional rules automatically dim (**grayed-out visual diagnostics**) for immediate root-cause visibility.
* **Modularity via Subflows**: Any flow can be published and embedded into other flows as a reusable **Subflow Node**, promoting cross-team reuse.

***

## 3. The Enterprise Container: Flow Suite

A **Flow Suite** is an enterprise-grade orchestration container that groups and runs multiple flows as a unified test regression, scheduled monitor, or data generation pipeline.

### Why Use Flow Suites?

* **Topological Dependency Execution**: Define execution order between flows (e.g., execute `Auth Setup` before `Order Processing`).
* **Suite-Wide Shared Variables**: Share environment parameters, base URLs, and global tokens across all child flows without hardcoding.
* **Unified Reporting & Quality Gates**: Consolidated execution reports with pass/fail counts, total duration, and SLA compliance metrics.
* **CI/CD Automation**: Execute entire suites in headless pipelines using `@quixa/cli`:
  ```bash theme={null}
  quixa run suite "Enterprise Regression Suite" --env staging --output junit
  ```
* **Scheduled Recurrence**: Trigger suites on automated background schedules using Quixa's built-in **3-Tier Hangfire Cron Engine**.

***

## Summary Matrix

| Level | Granularity | Primary Purpose | Execution Tool |
| :- | :- | :- | :- |
| **Node** | Atomic Step | Dispatches single API call, evaluates condition, or runs script. | Single Node Runner / Debugger |
| **Flow** | Directed Graph | Orchestrates multi-step business logic and transfers dynamic data. | Canvas Visual Runner / Webhook Trigger |
| **Suite** | Enterprise Container | Orchestrates cross-domain flows, regression suites, and scheduled pipelines. | Quixa Runner / Headless CLI (`@quixa/cli`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.