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

# How Flowra works

> The mental model for Flowra: projects, end users, tools, workflows, entry points, and data — in plain language.

This page is the single overview of how Flowra fits together. Other Product and Developers pages link here instead of redefining every term.

## What Flowra is

Flowra is one workspace where you **design, connect, and run** AI automations:

* **Build** agents and workflows in chat or the editor (fixed steps, AI-driven, or mixed)
* **Connect** apps (OAuth) and use a large tool catalog plus your own JS/Python tools
* **Reach people** via dashboard chat, MCP clients (Cursor / Claude), messengers (Telegram, WhatsApp, Slack, Discord, Gmail, Instagram, LINE, Bale, …), schedules, events, site widgets, or the API
* **Ground answers** with Knowledge (RAG), tables, and files
* **Operate** with executions, tool logs, optional human approval, sandbox, and live browser
* **Scale to many customers** with [external users](/product/external-users) under one [project](/product/projects-and-keys)

You do day-to-day work in the [dashboard](https://flowra.dev/dashboard). The same building blocks are available over the **API** when you embed Flowra in your product.

## The story in seven steps

1. You work inside a **project** (workspace). Lists follow the project in the sidebar switcher. See [Projects and API keys](/product/projects-and-keys).
2. Inside the project, the **End user** switcher picks which **external user** you act as — connections, chat, and much of the data stay separate per person. See [External users switcher](/product/external-users).
3. You describe a job in **chat**, or open **Workflows & Agents**, and Flowra turns that into a **workflow** or **agent**.
4. The recipe uses **tools** (send Slack, read Gmail, run your code). Related tools live in **toolkits**; **custom tools** and **MCP** are configured on the **project**, while **skills** attach to that end user’s agents.
5. Apps that need login use an **auth config** once (project-level); each end user then creates a **connected account** (OAuth) so tools act as them.
6. You **run** it from **entry points**: dashboard chat, messaging channels, schedule, events, a **widget**, MCP, or the API. See [Entry points and channels](/product/entry-points-and-channels).
7. Each run is a **thread** with an **execution** log. Optionally ground it with that user’s **knowledge** and **tables**, project **files**, plus **sandbox** or **browser** when needed.

```mermaid theme={null}
flowchart LR
  Project --> Shared[Auth config · tools · MCP]
  Project --> ExtUser[End user]
  ExtUser --> Conn[Connected account]
  Shared --> Tools
  Conn --> Tools
  Tools --> Flow[Workflow or Agent]
  Flow --> Entry[Entry points]
  Entry --> Thread[Thread and Execution]
```

## What lives where (nested)

```text theme={null}
Project
├── Shared: API keys · auth configs · tools/MCP · templates · external-user list · triggers · files
└── Each external user
    ├── Connections
    ├── Agents / workflows · skills · executions
    ├── Knowledge · tables · chat threads
    └── Tool calls using that user’s connections
```

Full nested map and when to split projects vs end users: [Projects and API keys](/product/projects-and-keys).

## Workflow vs agent

Both appear under **Workflows & Agents** in the dashboard.

| | Workflow (static) | Agent |
| - | - | - |
| Behavior | Fixed sequence of steps (graph) | AI decides the next tool each turn |
| Best for | Schedules, ETL, repeatable pipelines | Chat, support, open-ended tasks |
| How you run it | Manual run, cron, webhook/trigger | Chat, channels, embed, API threads |

A static workflow can still include AI **inside** a step. An agent has no fixed graph at the top level. For the developer-facing detail, see [Workflows and agents](/guides/workflows-and-agents).

## Glossary

| Term | Meaning |
| - | - |
| **Project** | Your Flowra workspace: security and API-key boundary. Holds shared setup (auth configs, tools, MCP) and contains external users. |
| **External user (eUID)** | An end-user identity *inside* a project — not your dashboard login. Selected with the **End user** switcher / `x-username`. |
| **End user switcher** | Sidebar control that sets which external user you act as for connections, chat, and per-user data. |
| **Tool** | One action (e.g. send a Slack message). See [Toolkits and tools](/product/toolkits-and-tools). |
| **Toolkit** | Group of related tools (e.g. Slack, Gmail). See [Toolkits and tools](/product/toolkits-and-tools). |
| **Auth config** | OAuth or API-key setup for a toolkit (project-level) so Flowra can call that service. |
| **Connected account** | One external user’s linked third-party identity after OAuth. |
| **Workflow / Agent** | The automation you build and run. |
| **Entry point** | How a run starts: chat, messaging channel, schedule, event, widget, MCP, or API. |
| **Messaging channel** | Two-way surface (Telegram, WhatsApp, Slack, Discord, Gmail, Instagram, LINE, Bale, …) — inbound message and reply. |
| **Trigger** | Rule that only **starts** a run (schedule or one-way event), without channel auto-reply. |
| **Thread** | Conversation or agent run session. |
| **Execution** | Recorded run with steps, status, and tool I/O. |
| **Knowledge** | Document collections for retrieval (RAG). |
| **Table / collection** | Structured data the agent can read and write. |
| **Skill** | Playbook or skill pack you attach so agents follow a procedure. See [Skills](/product/skills). |
| **MCP** | Model Context Protocol — expose or consume tools via MCP clients/servers. |
| **Widget / embed** | Chat surface on an external site bound to a workflow. |

## Where to go next

<CardGroup cols={2}>
  <Card title="Projects and API keys" icon="folder" href="/product/projects-and-keys">
    Workspace boundary and nested scope map.
  </Card>

  <Card title="External users switcher" icon="user" href="/product/external-users">
    Act as the right end user for connections and chat.
  </Card>

  <Card title="Toolkits and tools" icon="wrench" href="/product/toolkits-and-tools">
    Project catalog, custom tools, and Select Tools.
  </Card>

  <Card title="Skills" icon="book" href="/product/skills">
    End-user playbooks: My Skills, Browse, Select Skills.
  </Card>

  <Card title="Entry points and channels" icon="bolt" href="/product/entry-points-and-channels">
    Chat, messengers, schedule, events, and widgets.
  </Card>

  <Card title="First agent in chat" icon="rocket" href="/product/first-agent-in-chat">
    Build and test without leaving the dashboard.
  </Card>
</CardGroup>


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