# System architecture

Everything runs through a single Vivra server. It continuously reads the chain and writes through only two paths: the Buyback Bot (via the BuybackBurner contract) and the treasury job (Pons escrow claims). Agents call external services only through their tools.

[Diagram: architecture.png in the source repository — Frontend (dapp, landing, back-office) → Vivra server (analysis, API + WebSocket, orchestrator + 6 agents, Buyback Bot, treasury job, X/Telegram bots, Postgres + queues) → Robinhood Chain (Pons, tokens, BuybackBurner, CTO Fees wallet) and external services (Surplus, X API, Telegram, hosting, Pons CTO).]

The external-service connection covers inference, posts, groups, website hosting, and CTO applications.

## Recommended stack

| Component | Choice |
| --- | --- |
| Server | TypeScript on Node 22 |
| Data | Postgres; Redis with BullMQ for job queues |
| Chain | viem; Solidity contracts with Foundry, mainnet-fork tests |
| Agents | OpenAI-compatible client (`openai` npm) connected to Surplus, custom runner (build pack, T20) |
| Frontend | Next.js; email sign-in through an email delivery service (Resend, Postmark, or equivalent) |
| Hosting | API and workers on a container host; CTO token sites on Cloudflare Pages or Vercel |
| RPC | Alchemy, with a second provider as fallback |

## Environments

| Environment | Chain | Use |
| --- | --- | --- |
| Test | Robinhood Chain testnet, chain ID 46630 | development and contract takeover tests |
| Staging | mainnet fork | full-cycle dress rehearsal |
| Production | Robinhood Chain mainnet, chain ID 4663 | launch |