System Architecture

High-level architecture:

• Frontend: Next.js application.

• Auth & wallet access: Privy.

• Smart contracts: Base-deployed contracts for token lifecycle and perpetual engine.

• Data layer: Supabase Postgres + Realtime.

• Indexer: server-side process or API route that reads on-chain events and upserts normalized tables.

Core Components

• TokenFactory: social token lifecycle and bonding-curve trading.

• PerpEngine: perpetual market and position logic.

• PriceOracle: oracle registration and index-price access paths.

Runtime Data Paths

• On-chain reads for critical market/position state.

• Indexed tables (tokens, trades, price_candles, token_prices) for historical and real-time UX.

• Real-time subscriptions for chart and recent-trade updates.

Lifecycle & Risk Readiness

The current hardening branch adds two important production-oriented concepts:

• Explicit lifecycle readiness states on-chain (bonding, graduated-pending-liquidity/oracle, perp-live, paused)

• Explicit risk controls on the perpetual engine (market OI cap, skew cap, per-position notional cap, insurance fund accounting, and a global new-positions pause)

These are intended to ensure the UI and operator tooling do not treat graduated as synonymous with perp market live.

Treasury / Fee Visibility

The hardening branch now exposes fee-recipient routing and accrued-fee balances from TokenFactory and PerpEngine into frontend visibility surfaces. This is a step toward full treasury reconciliation and creator earnings transparency.