---
title: Concepts
path: concepts
status: published
---

# Concepts

The mental model behind ScaiFlow.

Read these in order on first contact:

1. **[Architecture](./concepts/architecture)** — the pieces (canvas, backend, compiler, ScaiGrid, ScaiCore) and how they fit together.
2. **[The flow graph](./concepts/flow-graph-model)** — nodes, edges, ports, the JSON shape on the wire.
3. **[The rigidity spectrum](./concepts/rigidity-spectrum)** — `@rigid`, `@guarded`, `@flexible`, and the "adaptive approval pattern" that composes the third with `@checkpoint`.
4. **[Node kinds](./concepts/node-kinds)** — the 24 building blocks, grouped by category.
5. **[Triggers](./concepts/triggers)** — entry nodes compile to top-level `IRTrigger` declarations, not to in-flow blocks. The closed set is `{api, webhook, schedule}`.
6. **[Models and the registry](./concepts/models-and-registry)** — declare every model your flow needs by role; LLM nodes pick a role.
7. **[Human-in-the-loop and checkpoints](./concepts/hitl-and-checkpoints)** — pause execution, route to a review queue, resume on response.
8. **[Sandboxes (ScaiBunker)](./concepts/sandboxes-and-bunkers)** — provision, exec, file I/O, destroy.
9. **[Queues (ScaiQueue)](./concepts/queues)** — topology, publish/consume, escalation.
10. **[Sub-flows](./concepts/sub-flows)** — compose flows from other deployed Cores.
11. **[Publish as model](./concepts/publish-as-model)** — turn a deployed Core into a chat model reachable over OpenAI-compatible chat completions.
12. **[Multi-tenancy and auth](./concepts/multi-tenancy-and-auth)** — ScaiKey OIDC, per-tenant credentials, per-flow ACLs.
13. **[Compilation targets](./concepts/ir-and-compilation-targets)** — YAML for ScaiGrid (default), SCIR MessagePack for verification, `.scai` text for inspection.