Architecture Overview

Technical architecture, data flow, and system design of XandScan

System Architecture

┌──────────────────────────────────────────────────┐
│              User Browser/Client                 │
└───────────────────┬──────────────────────────────┘
                    │
          ┌─────────▼─────────┐
          │   Next.js App     │
          │   (React 19)      │
          └─────────┬─────────┘
                    │
     ┌──────────────┴──────────────┐
     │                             │
┌────▼────┐               ┌───────▼────────┐
│ React   │               │   API Routes   │
│ Query   │               │   /api/prpc    │
└────┬────┘               └───────┬────────┘
     │                             │
┌────▼──────────┐          ┌──────▼────────┐
│ PNodeClient   │──────────│  Axios Client │
│ (with Circuit │          │  (Timeout:5s) │
│  Breaker)     │          └──────┬────────┘
└───────────────┘                 │
                          ┌───────▼────────┐
                          │  8 pNode RPC   │
                          │   Endpoints    │
                          │   (Port 6000)  │
                          └────────────────┘

Tech Stack

Frontend

• • Next.js 16.1+: React framework with App Router
• • React 19: Latest React with Server Components
• • TypeScript 5: Type-safe development
• • Tailwind CSS 4: Utility-first styling
• • Lucide React: Icon library
• • Recharts 3: Data visualization

Data Layer

• • TanStack React Query v5: Server state management
• • Axios: HTTP client with interceptors
• • Circuit Breaker Pattern: Fault tolerance
• • Smart Caching: 60s stale time, no auto-refetch

Performance

• • React.memo: Component memoization
• • Parallel Fetching: Simultaneous pNode queries
• • Code Splitting: Route-based lazy loading
• • Tree Shaking: Unused code elimination

Data Flow

Request Flow

1. 1. User Action

   User navigates to dashboard or nodes page

2. 2. React Query Hook

   Component calls useAllPNodes() or useNetworkStats()

3. 3. Cache Check

   React Query checks if data is cached and fresh (<60s old)

4. 4. PNodeClient Request

   If stale, PNodeClient fetches from pRPC endpoints

5. 5. Circuit Breaker

   Skips failing nodes, queries 8 endpoints in parallel

6. 6. Data Transform

   Raw pRPC data transformed to PNode type

7. 7. Cache Update

   React Query caches result for 60s

8. 8. Component Render

   Component receives data and renders UI

Key Components

PNodeClient

Core API client with resilience patterns:

• • 5-second timeout per request
• • Circuit breaker tracks failing nodes
• • Parallel execution across endpoints
• • No retry logic (fail fast)
• • Automatic data validation

React Query Hooks

Custom hooks for data fetching:

• • useAllPNodes() - Fetch all pNodes
• • usePNodeDetails(id) - Fetch specific node
• • useNetworkStats() - Network statistics
• • 60s stale time prevents excessive requests
• • No background refetching (explicit refresh only)

Intelligence Layer

AI-powered analytics:

• • generateNetworkEvents() - Detects events
• • assessNetworkRisk() - Risk analysis
• • calculateNetworkHealth() - Health scoring
• • Client-side computation using useMemo

Performance Optimizations

Bundle Size

• • Tree shaking removes unused code
• • Route-based code splitting
• • Dynamic imports for heavy components
• • Zero runtime dependencies in production

Rendering Strategy

• • Server Components for static content
• • Client Components for interactive UI
• • React.memo for expensive components
• • useMemo for complex calculations

Network Efficiency

• • Parallel pNode endpoint queries
• • 60s cache reduces API calls
• • Circuit breaker prevents slow requests
• • 5s timeout ensures fast failure

Security Considerations

• • No authentication required (read-only platform)
• • Environment variables for sensitive config
• • CORS configured for API routes
• • Input validation on all user inputs
• • XSS protection via React's automatic escaping
• • HTTPS enforced in production