Architecture
TechnicalSystem design, services, and data flow
Tech Stack
Next.js 15 (App Router)
React 19
TypeScript 5.9
Tailwind CSS 4
shadcn/ui
Radix UI
Vercel AI SDK v5
OpenAI GPT-4o
TanStack React Query
Jotai
Recharts
Leaflet
React-Leaflet
PostgreSQL
Prisma ORM
@solana/web3.js
Wallet Adapter
Project Structure
src/ ├── app/ # Next.js App Router pages │ ├── page.tsx # Homepage dashboard │ ├── pnodes/ # pNode explorer & detail pages │ ├── network/ # Network analytics (5 tabs) │ ├── analytics/ # Historical analytics │ ├── insights/ # AI insights │ ├── alerts/ # Alert management │ ├── compare/ # pNode comparison │ ├── watchlist/ # User watchlist │ ├── settings/ # App settings │ ├── help/ # Help & documentation │ ├── docs/ # In-app documentation │ └── api/ # API routes │ ├── chat/ # AI chat endpoint │ ├── prpc/ # pRPC proxy │ ├── pnodes/ # pNode endpoints │ ├── alerts/ # Alert endpoints │ └── analytics/ # Analytics endpoints ├── components/ │ ├── app-sidebar.tsx # Left sidebar navigation │ ├── app-header.tsx # Top header with controls │ ├── mobile-nav.tsx # Mobile bottom navigation │ ├── ai-chat.tsx # AI chat component │ ├── rewards-tracking.tsx # Rewards & epoch tracking │ ├── network-topology.tsx # Network visualization │ ├── pnodes/ # pNode-specific components │ ├── alerts/ # Alert components │ └── ui/ # shadcn/ui components ├── services/ │ ├── pnode.service.ts # pNode data fetching │ ├── analytics.service.ts # Analytics & predictions │ ├── alert.service.ts # Alert management │ ├── geoip.service.ts # GeoIP lookup │ └── websocket.service.ts # Real-time updates ├── lib/ │ ├── prisma.ts # Prisma client │ └── utils.ts # Utility functions └── types/ # TypeScript definitions
Service Layer
The application uses a service layer pattern to encapsulate business logic and external API calls.
PNodeService
pnode.service.tsCore service for fetching pNode data from Xandeum network
getPNodes()getPNodeDetails(id)getNetworkStats()getEpochInfo()AnalyticsService
analytics.service.tsHistorical data, predictions, and quantitative analysis
getHistory()getPredictions()getAnomalies()getLeaderboard()AlertService
alert.service.tsAlert creation, management, and notification delivery
createAlert()getAlerts()updateRule()dismissAlert()WebSocketService
websocket.service.tsReal-time updates via WebSocket with polling fallback
connect()subscribe()disconnect()onMessage()GeoIPService
geoip.service.tsGeographic location lookup for pNode IP addresses
lookupGeoIP(ip)getLocationForIP(ip)batchLookup()Data Flow
Database Schema
PostgreSQL with Prisma ORM for analytics persistence and alert management.
NetworkSnapshot
Historical network state at each index run
timestamptotalPNodesonlinePNodestotalStorageavgPerformancePNodeSnapshot
Per-pNode historical metrics
pubkeytimestampstatusstorageperformanceuptimeAlert
Generated alerts
typeseveritypnodeIdmessagestatuscreatedAtAlertRule
User-configured alert rules
typethresholdenablednotificationsReal-time Updates
How the platform maintains live data
Primary: WebSocket
Streaming connection for instant updates when available
Fallback: Polling
Configurable interval (15s, 30s, 1min, 5min) via settings
React Query handles caching with a 30-second stale time to reduce redundant network requests.
Key Design Decisions
API Route Proxy
All pRPC calls go through /api/prpc to avoid browser CORS restrictions
Service Abstraction
Business logic isolated in service classes for testability and reuse
Incremental Static Regeneration
Static pages with ISR for optimal performance
Dynamic Imports
Heavy components (maps, charts, globe) loaded on demand
Jotai State
Atomic state management for settings, watchlist, and UI preferences
React Query Caching
30s stale time balances freshness with performance