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

# System Architecture

> How Jinba Flow components work together

Jinba Flow consists of four main components that work together to enable workflow automation.

## Component Overview

<CardGroup cols={2}>
  <Card title="Flow Editor" icon="pen-to-square">
    Visual interface for creating workflows using Chat, Graph, or YAML
  </Card>

  <Card title="Manifest" icon="file-code">
    YAML representation of your workflow definition
  </Card>

  <Card title="Runner" icon="gears">
    Execution engine that processes manifests and runs steps
  </Card>

  <Card title="API / MCP" icon="server">
    External interfaces for triggering and integrating workflows
  </Card>
</CardGroup>

## Data Flow

```mermaid theme={null}
flowchart LR
    Editor["Editor<br/>(Design)"] --> Manifest["Manifest<br/>(YAML)"]
    Manifest --> Runner["Runner<br/>(Execute)"]
    Runner --> API["API / MCP<br/>(Deploy)"]
    API -.->|Feedback Loop| Editor
```

## Component Details

### 1. Flow Editor (Design Time)

The Flow Editor provides three methods to create workflows:

| Method           | Interface            | Best For                               |
| ---------------- | -------------------- | -------------------------------------- |
| **Chat Panel**   | Natural language     | Quick prototyping, non-technical users |
| **Graph Editor** | Visual drag-and-drop | Understanding flow structure           |
| **YAML Panel**   | Direct code editing  | Precise control, version control       |

All three methods produce the same output: a **Manifest**.

### 2. Manifest (Bridge)

The Manifest is a YAML document that defines your workflow:

```yaml theme={null}
steps:
  - id: step_id
    tool: TOOL_NAME
    input:
      - name: param
        value: "{{reference}}"
    needs: [dependency_step]
    when: "condition"
    forEach: "{{collection}}"
```

| Field     | Purpose                        |
| --------- | ------------------------------ |
| `id`      | Unique identifier for the step |
| `tool`    | The tool to execute            |
| `input`   | Parameters passed to the tool  |
| `needs`   | Dependencies on other steps    |
| `when`    | Conditional execution          |
| `forEach` | Loop over a collection         |

### 3. Runner (Execution Time)

The Runner interprets manifests and executes workflows:

<Steps>
  <Step title="Parse">
    Load and validate the manifest YAML
  </Step>

  <Step title="Resolve">
    Build dependency graph from `needs` fields
  </Step>

  <Step title="Execute">
    Run steps in topological order, parallelizing when possible
  </Step>

  <Step title="Handle">
    Manage errors, retries, and conditional skips
  </Step>

  <Step title="Return">
    Collect results and return to caller
  </Step>
</Steps>

**Key Capabilities:**

* Parallel execution of independent steps
* Variable resolution (`{{steps.*.result}}`)
* Credential injection from workspace secrets
* Timeout and retry management

### 4. API / MCP (Deployment)

Published workflows expose two integration interfaces:

| Interface      | Endpoint                                             | Use Case                 |
| -------------- | ---------------------------------------------------- | ------------------------ |
| **REST API**   | `POST /api/v2/external/flows/{flowId}/published-run` | Programmatic integration |
| **MCP Server** | Model Context Protocol                               | AI agent tools           |

**Authentication:**

* API Key required for all external calls
* Keys scoped to workspace
* Rate limiting applied

## Execution Flow

<Steps>
  <Step title="Trigger">
    API call, schedule, MCP invocation, or manual run starts execution
  </Step>

  <Step title="Load">
    Runner loads the published manifest version
  </Step>

  <Step title="Validate">
    Input parameters validated against defined schema
  </Step>

  <Step title="Execute">
    Steps run according to dependency graph
  </Step>

  <Step title="Return">
    Results returned via API response or MCP result
  </Step>
</Steps>

## Security Boundaries

| Boundary              | Protection                              |
| --------------------- | --------------------------------------- |
| **Editor → Manifest** | Schema validation prevents invalid YAML |
| **API → Runner**      | API key authentication required         |
| **Runner → Tools**    | Credential isolation per workspace      |
| **Runner → External** | Secure sandbox execution environment    |

## Workspace Isolation

Each workspace maintains:

* **Credentials**: API keys and OAuth tokens
* **Flows**: Workflow definitions
* **Versions**: Published snapshots
* **Execution History**: Run logs and artifacts

Workspaces are completely isolated from each other.

## What's Next?

<CardGroup cols={2}>
  <Card title="Execution Model" icon="timeline" href="./execution-model">
    Deep dive into how steps execute
  </Card>

  <Card title="API Reference" icon="code" href="/en/pages/basics/api">
    Learn about API endpoints
  </Card>
</CardGroup>