Architecture overview

Raidz uses a layered design: user-facing web and Telegram surfaces call an API boundary; deterministic domain packages define economic and policy behavior; PostgreSQL stores operational state; verifier services observe external evidence; EVM contracts enforce funding and release; analytics and Pons indexers build read models.

System map

                         ┌─────────────────────────────┐
                         │ X · Telegram · web · chain │
                         └──────────────┬──────────────┘
                                        │ consented reads / evidence
┌──────────────┐    HTTPS    ┌──────────▼───────────┐
│ Next.js web  ├────────────►│ Fastify API          │
│ + Reown UI   │◄────────────┤ identity · score     │
└──────┬───────┘             │ policy · read models │
       │                     └──────┬─────────┬──────┘
┌──────▼───────┐                    │         │
│ Telegram bot │              ┌─────▼───┐ ┌───▼──────────────┐
│ deep links   │              │Postgres │ │ domain package   │
└──────────────┘              └─────┬───┘ │ deterministic    │
                                    │     │ rules and schemas│
                          ┌─────────▼──┐  └──────────────────┘
                          │ workflows │   specified: Temporal
                          │ + queues  │   runtime: Redis
                          └─────┬─────┘
                                │ evidence jobs
                         ┌──────▼─────────┐
                         │ 3 verifiers   │
                         │ X/TG/web/chain│
                         └──────┬─────────┘
                                │ 2-of-3 EIP-712
┌───────────────────────────────▼──────────────────────────────┐
│ Robinhood Chain                                              │
│ CampaignFactory → CampaignEscrow ← VerifierRegistry          │
│ FeeRouter · RaidzRegistry · ReputationRegistry               │
│ Pons V2 factory/curve/pool state (read/index and future use) │
└───────────────────────────────┬──────────────────────────────┘
                                │ events
                         ┌──────▼─────────┐
                         │ index/read     │
                         │ models        │
                         └──────┬─────────┘
                                │ consented aggregates
                         ┌──────▼─────────┐
                         │ ClickHouse     │
                         │ analytics     │
                         └────────────────┘

Temporal, verifier workers, Pons indexing, and ClickHouse pipelines are architecture targets; they are not all implemented runtime services.

Repository boundaries

Path	Responsibility
`apps/web`	Marketing site, application shell, wallet UI, profile/Score/Radar/Market/project views, token transparency
`apps/api`	Fastify routes, validation, sessions, social/wallet linking, database adapter, readiness
`apps/bot`	Regular Telegram bot commands, role-aware copy, HTTPS deep links, in-memory rate limiting
`packages/domain`	Score, campaign policy, economics, lifecycle, analytics, attribution, proof schema, Pons registry
`database`	PostgreSQL base schema and image initialization
`contracts`	Solidity prototypes and Foundry tests
`deploy`	Runtime secret entrypoint and Nginx edge configuration
`docs`	Product, developer, security, operations, governance, and reference documentation
`reports`	Dated implementation and external-state receipts

Trust boundaries

Browser to API

Browser input is untrusted. Fastify validates bodies with Zod. The reverse proxy forwards /api/v1/* to the API. Session identifiers are HttpOnly, SameSite=Lax cookies and Secure in production.

API to providers

X OAuth uses authorization code with PKCE and state. Telegram Login uses a bot-token-derived signature and timestamp freshness. Provider responses are untrusted input and should be minimized before storage.

API to database

The identity store uses parameterized PostgreSQL queries and bounded pool/statement timeouts. Application start currently performs additive identity migrations. Production should move to explicit versioned migrations before schema evolution becomes complex.

Offchain to onchain

External observations do not directly move funds. Verifiers sign domain-separated payloads; escrow checks signer authorization, uniqueness/order, quorum, expiry, replay, campaign identity, creator, deliverable hash, and amount encoded in its schema.

Operator to privileged state

Credentials, verifier keys, wallets, and OAuth secrets are runtime-only. Public or repository content cannot grant authority. Every mutation must have exact target, expected state, recovery path, and independent receipt reconciliation.

Data placement

Keep social profiles, score features, content analysis, behavior, explanations, and consent records offchain. Put only minimal public settlement facts onchain: wallet, campaign identifier, content hash, value, timestamp, nonce, signature outcome, and state.

Redis is for cache, rate-limit, idempotency, and short-lived coordination—not authoritative settlement state. PostgreSQL is operational truth; onchain receipts are value-transfer truth; analytics stores derived consented events.

Known architecture gaps

The richer domain proof schema does not yet match the narrower Solidity attestation schema.
Campaign lifecycle names differ between the domain model, SQL enum, and claim contract; an orchestration mapping is required.
The public API exposes identity, score preview, policy preflight, and an empty mission read only—not campaign CRUD or settlement.
Redis is deployed but the current API does not consume it.
Temporal, production verifier services, Pons indexer, ClickHouse ingestion, object storage, and full observability are not implemented.
In-memory bot rate limiting resets on restart and is not shared across replicas.