# Core concepts

This page explains the mental model behind FetchCatch — useful before diving into the console or CLI.

## Multi-tenancy

Every FetchCatch account belongs to a **tenant**. Tenants are fully isolated:

- Flows, API sources, and runs never leak across tenants
- Secrets use envelope encryption per tenant
- API keys are scoped to a tenant

Within a tenant you can have multiple **workspaces** — think of them as projects or environments grouping related flows.

| Concept | Example | Stored in |
|---------|---------|-----------|
| Tenant | `acme-corp` | Login session |
| Workspace | `payments`, `onboarding` | Console + `.fetchcatch/project.json` |

When you run `fcc init --workspace payments`, you bind a local repo folder to that workspace slug. After `fcc login`, tenant and workspace IDs are written to `project.json`.

## Flows

A **flow** is a directed graph of **nodes** connected by **edges**. Each flow has:

- **Slug** — used in `/v1/evaluate/{slug}` (e.g. `approve-expense`)
- **Name** — human label in the console
- **Draft** — work-in-progress graph (editable)
- **Published version** — immutable snapshot callable via the API

You edit the draft in the designer or in `.fetchcatch/flows/{slug}.json`. **Publishing** makes a version live for evaluate calls.

### Node types (summary)

| Type | Role |
|------|------|
| `start` | Entry; declares input schema and optional response type |
| `http` | Calls an OpenAPI operation from an API source |
| `condition` | Branches on a JSONata boolean |
| `transform` | Computes a value with JSONata |
| `wait_for_event` | Pauses until an external resume |
| `decision` | Writes fields into the response accumulator |
| `end` | Terminates and returns the response |

→ Full reference: [Node types](flow-nodes.md)

## Runs

When something calls `/v1/evaluate/{slug}`, FetchCatch starts a **run**:

1. Validates input against the start node's schema
2. Walks the graph node by node
3. Either **completes** with a response, or **pauses** at a `wait_for_event` node

Paused runs stay in SQL (Durable Task). Resume with:

```
POST /v1/runs/{runId}/resume
{ "event": "user_confirmed", "payload": { ... } }
```

Inspect runs in the console under **Runs** — see step-by-step output, errors, and timing.

→ [Runs & debugging](runs.md)

## Response types

A **response type** is a named schema (flat fields) for flow output. Bind one on the start node so that:

- Defaults are seeded at run start
- Each `decision` node merges `responseValues`
- The `end` node validates required fields and types

This gives callers a stable JSON contract without ad-hoc payloads per branch.

→ [Response types](response-types.md)

## API sources

An **API source** is an ingested OpenAPI (Swagger) document. Operations become draggable **HTTP nodes** in the designer. FetchCatch handles SSRF-safe outbound calls and attaches **auth profiles** (API keys, OAuth) per source.

→ [API sources](api-sources.md)

## Auth profiles

**Auth profiles** store credentials for calling your backends — not for calling FetchCatch. Link a profile to an API source so HTTP nodes authenticate correctly (Bearer token, OAuth refresh, etc.).

Configure in the console under **Auth profiles**.

## Sync model (CLI)

The CLI treats your repo as the authoring surface:

| Server | Local |
|--------|-------|
| Manifest + hashes | `sync-state.json` |
| Flow documents | `.fetchcatch/flows/*.json` |
| Response types | `.fetchcatch/response-types/*.json` |

`fcc pull` downloads. `fcc apply` uploads (including **flow deletions** when a local file is removed). Hashes detect conflicts if someone else changed the server.

→ [Sync & CI](sync-and-ci.md)

## Console vs CLI — when to use which

| Task | Best tool |
|------|-----------|
| First-time setup, API sources | Console |
| Visual layout, expression intellisense | Console |
| Code review of rule changes | CLI + git |
| CI deploy of rules | CLI (`fcc apply`) |
| AI agent batch edits | CLI + `.fetchcatch/` |

Most teams use **both**: design in the console, pull to git, then iterate via PRs.

## Security summary

| Layer | Mechanism |
|-------|-----------|
| Console login | Email/password session |
| CLI login | Browser device flow or token |
| Evaluate API | Tenant API keys |
| Outbound HTTP | SSRF protection, tenant-scoped secrets |
| Data at rest | Envelope encryption for sensitive fields |

→ [API keys](api-keys.md)