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

# Architecture

> System overview, component breakdown, and data flow.

## Components

| Component | Role                                                                                                                                              |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client/` | Next.js 14 frontend — onboarding, wallet profiles, dashboard, send/swap, WalletConnect, invoices                                                  |
| `server/` | Express API — inline risk analysis, queue management, Safe Transaction Service integration, address derivation, relay execution, Zerion portfolio |
| `agent/`  | NanoBot/Hermes skill pack — Telegram commands, deep analysis, screening decisions, pattern recording                                              |

```mermaid theme={null}
flowchart TD
    U[User Browser] -->|Privy login — Google + embedded wallet, or wallet login| C[Client :3000]
    D[DApp e.g. PancakeSwap] -->|WalletConnect| C
    C -->|POST /queue — SafeTx, EIP-712 signed 1-of-2| S[Server :3001]
    S -->|propose 1/2| TS[Safe Transaction Service]
    TS -->|visible + confirmable| SA[app.safe.global]
    S -->|analyzeRisk inline| R{Risk Score}
    R -->|< 40 APPROVE| OC[NanoBot/Hermes Agent]
    R -->|40-70 REVIEW| OC
    R -->|> 70 BLOCK| OC
    OC -->|REVIEW: deep-analyze| EXT[GoPlus / Honeypot.is]
    EXT -->|address + token report| OC
    OC <-->|REVIEW: report + buttons\nBLOCK: alert| TG[Telegram / User]
    OC -->|confirm 2/2 via service| TS
    OC -->|execTransaction — agent pays gas| BC[BNB Chain]
    SA -->|override: backup key confirms + executes| BC
    BC -->|txHash| C
    BC -->|confirmed| OC
    OC -->|record-pattern| P[(patterns)]
```

## Client

* **Next.js 14** App Router, React 18, TypeScript, Tailwind CSS, Framer Motion
* **Privy** auth — Google OAuth + embedded wallet, or **wallet login** (MetaMask / Rabby as the signing key), plus a signature-free backup-key link
* Wallets are Safe multisigs with [computed profiles](/technology/signing#wallet-profiles) — starter / guarded / protected / detached
* Signs standard SafeTxs (EIP-712), 1 of the threshold, then POSTs to `/queue`
* **WalletConnect v2** — acts as a wallet for DApps; requests flow through the same pipeline
* **Portfolio** via Zerion API (live balances, prices, 24h change)

## Server

* **Express** with TypeScript (`tsx` for dev, PM2 for production)
* Runs `analyzeRisk()` inline on every `/queue` request — no async roundtrip
* **Hard-validates every proposal**: signature recovery against the recorded owner set, threshold arithmetic for screening-off, and owner-management transitions
* Mirrors every proposal to the **Safe Transaction Service** so it appears in app.safe.global at 1/2; a `safeSync` worker reconciles transactions confirmed or executed there directly
* **Relays execution**: the agent EOA submits `execTransaction` and pays BNB gas — relay-only (no agent signature) whenever user signatures meet the threshold
* Derives addresses server-side through a [versioned registry](/technology/signing#address-derivation); user records and transactions persist in Supabase (Postgres)

## Agent

* **NanoBot/Hermes skill pack** — holds the agent owner key
* Responds to Telegram commands from the owner
* Runs deep analysis (GoPlus + Honeypot.is) on REVIEW-tier transactions
* Records patterns after every confirmed transaction
* **Never signs unscreened transactions** — with screening off it either relays only (v2) or, for [legacy v1 accounts](/technology/legacy), co-signs by explicit exemption

## Data Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant S as Server
    participant TS as Safe Tx Service
    participant OC as NanoBot/Hermes Agent
    participant EXT as GoPlus / Honeypot.is
    participant TG as Telegram
    participant BC as BNB Chain

    C->>S: POST /queue {SafeTx, EIP-712 signature 1-of-2}
    S->>TS: propose (1/2 in app.safe.global)
    S->>S: analyzeRisk() → score
    S->>OC: notify (verdict + score)
    alt APPROVE
        OC->>TS: confirm (2/2)
        OC->>BC: execTransaction (agent pays gas)
        BC-->>C: txHash
        OC->>S: record-pattern
    else REVIEW
        OC->>EXT: deep-analyze (recipient + token)
        EXT-->>OC: address reputation, token security
        OC->>TG: analysis report + [Approve] [Reject]
        TG-->>OC: user responds
        OC->>BC: execTransaction (if approved)
        OC->>S: record-pattern
    else BLOCK
        OC->>TG: blocked alert
        Note over C,BC: Override: user confirms with backup key in the Safe app — safeSync reconciles
    end
```

Rejections execute a **pre-signed empty transaction at the same nonce**, so a rejected proposal never leaves a nonce hole blocking later transactions.

## State

| Store                    | Purpose                                                                                             |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| Supabase (Postgres)      | User records (owner sets, thresholds, immutable creation snapshots), transaction queue and outcomes |
| Safe Transaction Service | Proposal mirror — the source the Safe app reads and writes                                          |
| `state.json`             | Screening mode and agent decisions (agent runtime)                                                  |
| `patterns.json`          | Learned behavioral patterns (agent runtime)                                                         |

## Tech Stack

| Layer           | Technology                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| Chain           | BNB Chain (BSC), Chain ID 56                                                                            |
| Smart Account   | Safe 1.4.1 multisig — standard SafeTx flow via the Safe Transaction Service                             |
| Gas             | Agent EOA relays `execTransaction` and pays BNB (ERC-4337/Pimlico survives only for legacy queued rows) |
| Frontend        | Next.js 14, React 18, TypeScript, Tailwind CSS, Framer Motion                                           |
| Auth            | Privy (Google OAuth + embedded wallets, wallet login, backup-key linking)                               |
| Blockchain libs | viem, @safe-global/protocol-kit + api-kit                                                               |
| Backend         | Express, Supabase (Postgres), tsx (dev), PM2 (production)                                               |
| AI Agent        | NanoBot/Hermes with Qwen3-235B / Claude Sonnet 4.5 via OpenRouter                                       |