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

# Architecture

> How the gateway, inference engine, tool system, and RAG layer work together.

## System diagram

<Frame>
  <img src="https://mintcdn.com/deepmako/h23j78ELTn8cVKXM/images/architecture.png?fit=max&auto=format&n=h23j78ELTn8cVKXM&q=85&s=e92a6f03b582b91a118a0e29ce6c8330" alt="Mako system architecture" width="1024" height="1024" data-path="images/architecture.png" />
</Frame>

## Request lifecycle

<Steps>
  <Step title="Authentication">
    The gateway validates the `x-wallet-address` header and checks the `Authorization` bearer token against the API key database. If credits are enabled, it verifies the user has sufficient balance.
  </Step>

  <Step title="Model routing">
    The gateway routes the request to the appropriate inference backend based on the `model` field. The default production model is the **32B Conductor**.
  </Step>

  <Step title="Knowledge injection">
    Before inference, the gateway scans the user's message against 85+ keyword triggers. If a match is found (e.g., the user mentions "aerodrome" or "virtuals"), relevant project context is injected as a system message — up to 2 projects, \~500 tokens.
  </Step>

  <Step title="Agentic tool loop">
    The model's response is checked for tool calls. If found, the gateway executes the tool, feeds the result back to the model, and loops — up to **8 rounds**. The gateway also detects when the model is "stalling" (saying "let me check..." without actually calling a tool) and nudges it.
  </Step>

  <Step title="Auto-chaining">
    When a `web_search` returns results, the gateway automatically reads any tweet URLs via `read_tweet` and extracts the top non-tweet page via `web_extract` — all without additional model round-trips.
  </Step>

  <Step title="Response + billing">
    The final text response is returned in OpenAI format. Credits are deducted based on total token usage across all tool rounds.
  </Step>
</Steps>

## Tool system

The gateway has **16 built-in tools**, all read-only:

| Category      | Tools                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **On-chain**  | `get_eth_balance`, `get_token_balance`, `get_token_info`, `get_gas_price`, `get_block`, `get_tx_count`, `is_contract`, `resolve_ens`, `get_transaction` |
| **Market**    | `get_crypto_price`                                                                                                                                      |
| **Web**       | `web_search`, `web_extract`, `read_tweet`, `find_music`                                                                                                 |
| **Knowledge** | `knowledge_search`                                                                                                                                      |
| **Meta**      | `list_tools`                                                                                                                                            |

Tools are defined as a registry with descriptions, parameter schemas, and async execution functions. The gateway generates tool definitions from this registry and sends them with every inference call.

## Knowledge base (RAG)

The gateway includes a curated knowledge base of Base ecosystem projects, loaded at startup. Each entry contains metadata, keywords, and detailed context.

Two retrieval modes:

1. **Auto-injection** — Keywords in the user's message trigger automatic context injection before inference. Top 2 matches, \~500 tokens.
2. **Explicit search** — The `knowledge_search` tool lets the model query the knowledge base directly. Returns up to 5 results with fuzzy scoring.

## Inference engine

The gateway manages model routing, cold start handling, and response formatting. It supports multiple backends and handles the translation between different inference APIs transparently.

Key features:

* **Cold start management** — Automatic polling and retry for models scaling from zero
* **Fallback routing** — Graceful degradation if the primary backend is unavailable
* **Format normalization** — All responses are returned in OpenAI Chat Completions format regardless of the underlying backend