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

# System overview

> Components, responsibilities, and infrastructure.

## Component map

```
Advertiser / AI lab          Human              Group owner
      │                        │                     │
Canvas AI · buy flow    Telegram Bot API     Canvas AI · register
      │                        │                     │
      └──────────────┬─────────┘                     │
                     ▼                               │
              Agent Server · Railway ◄───────────────┘
              (Node.js / TypeScript)
                     │
              ┌──────┴──────┐
              ▼             ▼
           Postgres     Conversation LLM
           (state)      (dialogue turns)
                             │
                        Kimi inference
                        (transcript scoring)
                             │
                    ① logCompletion
                    ② releasePayout
                             │
                     Escrow Contract · Base
                     (holds USDC · logs · pays out)
```

## Components

### Agent server (Railway)

The always-on Node.js process that runs every verification. Responsibilities:

* Receives Telegram webhooks on new group joins
* Checks Postgres for group registration and active campaign budget
* Manages per-user verification state machine
* Calls the conversational LLM to generate agent turns
* Submits transcripts to Kimi for scoring
* Fires `logCompletion` and `releasePayout` contract calls
* Delivers completion data to advertisers

### Postgres

| Table           | Contents                                                      |
| --------------- | ------------------------------------------------------------- |
| `groups`        | Registered groups, topic, floor price, payout wallet          |
| `campaigns`     | Advertiser campaigns, bid price, budget, group assignments    |
| `verifications` | Per-user verification state, conversation history, Kimi score |
| `user_sessions` | Active conversation state per Telegram user ID                |

### Conversational LLM

Generates dialogue turns from the advertiser brief and group context. Decides whether to probe based on response length and specificity. Closes the conversation after 2–3 agent turns. Does not score responses.

### Kimi (Moonshot AI)

Receives the full transcript after the conversation closes. Returns a quality score between 0 and 1. Score at or above `KIMI_PASS_THRESHOLD` triggers `releasePayout`. Score below threshold triggers re-prompt.

API endpoint: `api.moonshot.ai/v1`\
Relevant env vars: `KIMI_API_KEY`, `KIMI_BASE_URL`, `KIMI_MODEL`, `KIMI_PASS_THRESHOLD`

### Escrow contract (Base mainnet)

Address: `0xf808b264E13Bf809C8e86afaF4e14c200931101E`

Handles advertiser deposits, per-completion onchain logging, and USDC release to group owner wallets. Full function reference: [Smart contract](/architecture/smart-contract).

### Telegram bot (`@CanvasVerificationBot`)

* Detects join events via Telegram webhook
* Posts a brief verification notice in the group chat
* Opens a DM with the joining user
* Relays turns between user and conversational LLM
* Restricts and unrestricts users based on verification outcome

## Infrastructure

| Layer                | Service                                       |
| -------------------- | --------------------------------------------- |
| Agent server         | Railway (Node.js, always-on)                  |
| Database             | Railway Postgres                              |
| Frontend / dashboard | Vercel                                        |
| DNS                  | Cloudflare                                    |
| Blockchain           | Base mainnet                                  |
| Bot                  | Telegram BotFather (`@CanvasVerificationBot`) |
| Conversational LLM   | Lightweight model (e.g. Gemini Flash 2.0)     |
| Quality scoring      | Kimi · Moonshot AI                            |