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

# How Hive works

> The architecture behind Hive: the web app, API and workers, Postgres with row-level security, job queue, connectors, model gateway and the sense-plan-act loop.

This page explains how Hive is put together, for technical evaluators and developers. It follows data from your tools, through detection and planning, to a decision and an action — and shows where each safety control sits.

## The big picture

```mermaid theme={null}
flowchart TB
  subgraph Client
    W[Web app<br/>single-page React app]
  end
  subgraph Hive platform - Frankfurt
    A[API<br/>Hono on Node.js]
    K[Workers<br/>background jobs]
    D[(Postgres<br/>row-level security, pgvector)]
    R[(Redis<br/>cache, rate limits, locks)]
    Q[Job queue<br/>signed, at-least-once]
  end
  subgraph Outside
    N[Connector platform<br/>OAuth, tokens, API calls]
    T[Your tools]
    M[AI model providers<br/>via gateway or direct]
    X[MCP servers]
  end
  W -->|Signed-in session| A
  A --> D
  A --> R
  A --> Q
  Q --> K
  K --> D
  K --> N --> T
  K --> X
  K --> M
  A --> M
```

| Component | What it does |
| - | - |
| **Web app** | A client-side React app. It holds no business logic of its own and talks to the API over HTTPS. |
| **API** | Verifies every request's sign-in session, resolves the workspace, and serves reads and writes. |
| **Workers** | Run background jobs: collecting data, detecting signals, planning, executing approved actions, running workflows and agents. |
| **Postgres** | The system of record. Row-level security is forced on workspace tables; vector search powers knowledge retrieval. |
| **Job queue** | Delivers signed jobs at least once, with per-workspace idempotency keys and fairness caps so one busy workspace cannot starve another. |
| **Redis** | Caching, rate limiting, scheduler locks and webhook de-duplication. |
| **Connector platform** | Handles OAuth sign-in with your tools, stores their tokens, and makes API calls on Hive's behalf. |
| **Model providers** | Language, embedding and image models. See [AI and models](/security/ai-and-models). |

## The loop: sense, plan, decide, act, learn

Hive's core is a loop that runs continuously for every workspace.

```mermaid theme={null}
flowchart LR
  C[Collect<br/>read your tools] --> S[Sense<br/>detect signals]
  S --> P[Plan<br/>AI proposes a next step]
  P --> G{Policy<br/>deterministic rules}
  G -->|Auto within limits| E[Execute]
  G -->|Needs a person| H[Approval]
  G -->|Not yet trusted| SH[Shadow]
  H --> E
  E --> L[Learn<br/>outcomes update memory]
  L --> S
  E --> AU[Audit receipt]
```

<Steps>
  <Step title="Collect">
    Every hour, and immediately after you connect a tool, workers read from your connected accounts through the connector platform. Some providers also push changes in real time through signed webhooks. Files from Google Drive, Dropbox, OneDrive and SharePoint are synced into the knowledge base with their permissions.
  </Step>

  <Step title="Sense">
    Detectors compare what they read with learned baselines. A statistical detection only fires when it is well outside the norm on at least two of the last three readings, so a single spike never raises a signal. Built-in detectors also watch email threads and specific business processes. See [Signals](/signals/overview).
  </Step>

  <Step title="Plan">
    For a signal worth acting on, the AI drafts a plan: a sequence of typed actions with structured parameters, grounded in evidence from your tools and the Business Brain.
  </Step>

  <Step title="Decide">
    A deterministic policy engine — code, not a model — checks the kill switch, the action's autonomy rung, its blast-radius tier, confidence, spend caps, rate limits and error budgets. The outcome is run, ask a person, or simulate. See [Safety and control](/admin/safety-and-control).
  </Step>

  <Step title="Act">
    An isolated executor, the only component that can use your credentials, carries out the approved action and records a receipt. Reversible actions record how to undo them.
  </Step>

  <Step title="Learn">
    Approvals, denials and outcomes feed execution memory. New behaviours start in shadow and only take effect when a person activates them. See [Learned behaviours](/brain/learned-behaviours).
  </Step>
</Steps>

## Requests from people

Ask Hive, the workflow builder and Agent Studio follow the same pattern. The API verifies your session and role, gathers the context the request needs, and calls a model. Anything that would change something in your tools becomes a typed proposal and goes through the same policy engine as the loop.

## Workflows and agents at run time

* A **workflow** is a graph of steps compiled and validated at deploy time into an immutable release. Each run executes that release step by step on the workers, persisting every step so a run survives restarts. See [Workflow builder](/workflows/workflow-builder).
* An **agent** is a saved, versioned configuration — instructions, knowledge, tools and governance limits — that runs with a budget of time, model calls and actions. See [Agent Studio](/agents/agent-studio).
* Both can be started by people, schedules, forms or other agents, and every external action they propose passes the policy engine.

## Where the safety controls sit

| Control | Where it is enforced |
| - | - |
| Workspace isolation | Every query, and forced row-level security in Postgres |
| Authentication | API, on every request |
| Roles and approvals | API and policy engine |
| Kill switch, caps and breakers | Policy engine, before every action |
| Credential access | Executor only; never the model |
| Untrusted content | Marked as data in every prompt |
| Tool integrity | MCP tool fingerprints pinned at connect time |
| Audit | Written for every executed, approved or undone action |

## Related

<CardGroup cols={2}>
  <Card title="Security overview" icon="lock" href="/security/overview">
    The protections in plain language.
  </Card>

  <Card title="Infrastructure" icon="server" href="/security/infrastructure">
    Providers and regions.
  </Card>

  <Card title="Developer overview" icon="code" href="/developers/overview">
    What you can build on Hive.
  </Card>

  <Card title="Key concepts" icon="book" href="/get-started/key-concepts">
    The vocabulary of Hive.
  </Card>
</CardGroup>