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

# Platform Architecture

> How Bothive's five-layer architecture powers production-grade AI agents.

## The five layers

<CardGroup cols={2}>
  <Card title="1. Authoring Layer" icon="pen-to-square" className="glass-effect">
    Where agents are defined. **HiveLang v5**, the visual Builder, and HiveMind (plain-English AI assistant) all produce a structured agent definition that feeds into the runtime.
  </Card>

  <Card title="2. Runtime Layer" icon="microchip" className="glass-effect">
    The execution engine. Routes to the right model, injects memory, selects tools, generates responses, and handles retries — all in a sandboxed, tenant-isolated environment.
  </Card>

  <Card title="3. Integration Layer" icon="plug" className="glass-effect">
    How agents touch external systems. 25+ native integrations with managed OAuth, plus custom HiveLang integrations for any REST or GraphQL API.
  </Card>

  <Card title="4. Delivery Layer" icon="signal" className="glass-effect">
    How agents reach users. One agent definition deploys to Web, Telegram, Slack, WhatsApp, or API — normalized through the channel binding system.
  </Card>
</CardGroup>

<Card title="5. Observability Layer" icon="chart-line" className="glass-effect">
  The operational surface. Every run produces a structured trace: user input, context loaded, model selected, tools called, latency, errors, and output. No black boxes.
</Card>

## Request flow

Here's what happens when a user sends a message to your agent:

<Steps>
  <Step title="Message received">
    The channel adapter (Web, Telegram, Slack, or API) receives the raw message and normalizes it into Bothive's internal message format.
  </Step>

  <Step title="Session & memory resolved">
    The runtime looks up the session ID, loads conversation history, injects any persistent memory for this user, and builds the context window.
  </Step>

  <Step title="Model routing">
    Based on agent config (or dynamic routing rules in HiveLang), the runtime picks the right model — `gpt-4o`, `claude-3.5-sonnet`, `gemini-1.5-pro`, or a custom endpoint.
  </Step>

  <Step title="Tool selection & execution">
    If the model decides to use a tool, the runtime validates the capability, executes it against the integration layer, handles auth refresh if needed, and returns structured output.
  </Step>

  <Step title="Response generated">
    The model generates its reply using the message, context, and tool results. The runtime streams or returns the response to the channel.
  </Step>

  <Step title="Trace written">
    A complete trace is written: timestamps, latency per step, tool arguments, errors, cost, and output. Available immediately in the Observability dashboard.
  </Step>
</Steps>

## Infrastructure components

| Component               | Role                                     | Technology                 |
| ----------------------- | ---------------------------------------- | -------------------------- |
| **Primary store**       | Agent definitions, user sessions, memory | Postgres / Supabase        |
| **Speed layer**         | Session cache, rate limiting, hot memory | Redis                      |
| **Task queue**          | Slow integration work, scheduled bots    | Background workers         |
| **Model router**        | Fast vs deep reasoning selection         | Bothive routing layer      |
| **Observability store** | Run traces, latency, errors              | Structured trace log       |
| **Auth vault**          | OAuth tokens, API keys, secrets          | Encrypted credential store |

## HiveLang v5 and the runtime

When you write a HiveLang file, it compiles to a structured AST that the runtime executes:

```hivelang theme={null}
bot AnalyticsAgent {
  description: "Answers business analytics questions"

  capabilities {
    database.query
    charts.generate
    slack.postMessage
  }

  instructions {
    You are a business analytics assistant.
    Answer questions with data. Always cite your source.
    When unsure, query the database before answering.
  }

  on schedule.daily {
    data = call database.query with {
      sql: "SELECT revenue, date FROM daily_stats ORDER BY date DESC LIMIT 7"
    }
    chart = call charts.generate with { data: data, type: "line" }
    call slack.postMessage with {
      channel: "#analytics",
      text: "Daily revenue trend:",
      attachment: chart
    }
  }
}
```

The `bot`, `capabilities`, `instructions`, and `on` blocks are parsed by the v5 parser into typed AST nodes and executed by the Bothive runtime.

## Multi-agent swarm architecture

For complex workflows, the swarm layer coordinates multiple agents:

```hivelang theme={null}
swarm ContentTeam {
  description: "Researches, writes, and publishes content"

  agent Researcher {
    role: "Find accurate, current information on the topic"
    capabilities { web.search, knowledgebase.query }
  }

  agent Writer {
    role: "Transform research into engaging articles"
    capabilities { ai.generate }
  }

  agent Publisher {
    role: "Post to the appropriate channels"
    capabilities { notion.createPage, twitter.post }
  }

  on input {
    research = delegate to Researcher with { query: input }
    article = delegate to Writer with { research: research }
    delegate to Publisher with { content: article }
  }
}
```

Each agent in a swarm runs in its own execution context but shares memory through the swarm's memory namespace.

## Tenant isolation

Every end-user session runs in an isolated context:

* **Memory is scoped** per `(bot_id, user_id)` — one user's memory never leaks to another
* **Tool executions** are sandboxed per session
* **Observability** is filterable per user or tenant
* **Rate limits** apply per user, not per bot

## Next reads

<CardGroup cols={3}>
  <Card title="Memory System" icon="brain" href="./memory" className="glass-effect" />

  <Card title="Integrations" icon="plug" href="./integrations" className="glass-effect" />

  <Card title="Observability" icon="chart-line" href="./observability" className="glass-effect" />
</CardGroup>