Architecture

Deriverse is a trading analytics platform built on Next.js that provides comprehensive analysis of Solana blockchain trading activity. It integrates real-time blockchain data with persistent storage to offer personalized trading journals.

System Overview

The application follows a modern client-server architecture with blockchain integration:

Architecture Layers

Frontend Layer

The presentation layer built with React 19 and Next.js 16 App Router.

User Interface: TailwindCSS with Framer Motion animations
State Management: React hooks with custom useWalletConnection
Routing: Next.js App Router for server-side rendering
Wallet Integration: Jupiter Wallet Adapter for unified wallet support

Service Layer

Business logic and external API integration located in src/services/.

SupabaseWalletService: Wallet persistence and lookup
SupabaseTradeService: Trade data caching and retrieval
HeliusService: Blockchain transaction fetching
DeriverseTradeService: Trade analytics processing

Data Layer

PostgreSQL database managed by Supabase with Row Level Security.

Persistence: User wallets and trade data
Caching: 24-hour cache for blockchain data
Security: RLS policies ensure data isolation

Component Structure

The codebase is organized following a feature-based architecture:

src/
├── app/                    # Next.js App Router
│   ├── layout.tsx         # Root layout with providers
│   ├── page.tsx           # Home page
│   └── providers.tsx      # Wallet & context providers
├── components/
│   ├── features/         # Feature-specific components
│   │   ├── Home.tsx      # Dashboard view
│   │   ├── Journal.tsx   # Trade journal
│   │   └── TradeHistory.tsx  # Trade list
│   ├── layout/           # Layout components
│   │   ├── GlassmorphismNavbar.tsx
│   │   └── TabNavigation.tsx
│   └── ui/               # Atomic UI components
│       ├── NewUserModal.tsx
│       └── LoadingScreen.tsx
├── lib/                  # Utilities & hooks
│   ├── hooks/            # Custom React hooks
│   ├── constants.ts      # App-wide configuration
│   └── tradeFilters.ts   # Filtering logic
└── services/             # API & DB clients

The component structure follows atomic design principles with clear separation between features, layout, and reusable UI elements.

Technology Stack

Core Framework

Next.js 16

App Router for server-side rendering, routing, and API routes.

React 19

Latest React with improved concurrency and suspense features.

Infrastructure

Supabase

PostgreSQL database with real-time subscriptions and authentication.

Solana Web3.js

Blockchain interaction and transaction parsing.

Jupiter Wallet Adapter

Unified wallet connection supporting Phantom, Solflare, and more.

Frontend Technologies

Technology	Purpose	Version
TypeScript	Type safety across the codebase	5.x
TailwindCSS	Utility-first styling system	4.x
Framer Motion	Animation library for smooth transitions	12.x
Geist Fonts	Unified typography (Sans, Mono, Pixel Grid)	1.7
Recharts	Data visualization for analytics	3.7
Sonner	Toast notifications	2.0

Data Flow Patterns

Wallet Connection Flow

The application uses a unified wallet connection flow that handles both new and returning users:

Connect

User triggers Jupiter Wallet Adapter through the UI. Supported wallets include Phantom, Solflare, and manual address entry.

Verify

SupabaseWalletService checks if the wallet exists in the database (user_wallets table).

New users are guided through NewUserModal for registration with network selection and wallet provider metadata.

Activate

App switches to active mode, fetching real data from blockchain via Helius and Deriverse SDK.

Data Modes

Deriverse operates in two distinct modes:

Mock Mode
Real Mode (Devnet)

Local Development & Demos

Uses mockData.ts for rapid UI testing
No blockchain or database connection required
Ideal for exploring features without wallet setup
Banner indicates mock data is active

Trade Data Pipeline

Trade data flows through multiple processing stages:

The caching strategy balances data freshness with RPC efficiency. Trades older than 24 hours show a “Refresh” button to fetch updated data.

State Management

Connection State

The useWalletConnection hook wraps Jupiter’s wallet adapter and provides:

interface WalletConnectionState {
  walletAddress: string | null;
  connected: boolean;
  isWalletModalOpen: boolean;
  connect: () => void;
  disconnect: () => void;
}

Persistence Strategy

User Wallets

Stored in Supabase user_wallets table for cross-device persistence and recent wallet tracking.

Trades

Cached in trades table after blockchain fetch. Filtered locally for real-time analytics.

Annotations

Journal entries stored in trade_annotations table, synced from localStorage fallback.

UI State

Ephemeral React state for filters, modals, and temporary data. Cleared on navigation.

Security & Authentication

Deriverse does not implement user authentication. Wallet addresses serve as unique identifiers, with data isolation enforced through Supabase Row Level Security policies.

Security Measures

Environment Variables: Sensitive keys (RPC URLs, Supabase credentials) stored in .env.local
RLS Policies: Users can only access trades associated with their wallet address
JWT Tokens: Secure communication between frontend and Supabase
No Private Keys: Wallet adapters handle signing; private keys never leave user’s wallet

Local Development

Run the development server with:

npm run dev

Access the app at http://localhost:3000. Hot module reloading is enabled for rapid iteration.

Use mock data mode (default) for UI development without blockchain connectivity. Switch to real mode by connecting a wallet.

Performance Considerations

Optimization Strategies

Static Generation: Next.js pre-renders pages at build time where possible
Incremental Loading: Trades load in batches to prevent UI blocking
Client-Side Caching: Supabase caches reduce redundant blockchain queries
Lazy Loading: Wallet adapter and heavy components load on-demand
Code Splitting: Next.js automatically splits code by route

Resource Usage

Resource	Limit (Free Tier)	Usage Pattern
Supabase DB	500 MB	~420 KB per 1,000 trades
RPC Calls	Varies by provider	Cached 24 hours
Vercel Bandwidth	100 GB/month	Minimal (static assets)

Last Updated: February 2026 For database schema details, see Database. For deployment configuration, see Deployment.

Get Started

Core Features

Platform

Development

System Overview

Architecture Layers

Component Structure

Technology Stack

Core Framework

Next.js 16

React 19

Infrastructure

Supabase

Solana Web3.js

Jupiter Wallet Adapter

Frontend Technologies

Data Flow Patterns

Wallet Connection Flow

Data Modes

Trade Data Pipeline

State Management

Connection State

Persistence Strategy

User Wallets

Trades

Annotations

UI State

Security & Authentication

Security Measures

Local Development

Performance Considerations

Optimization Strategies

Resource Usage

Build docs developers (and LLMs) love

Get Started

Core Features

Platform

Development

​System Overview

​Architecture Layers

​Component Structure

​Technology Stack

​Core Framework

Next.js 16

React 19

​Infrastructure

Supabase

Solana Web3.js

Jupiter Wallet Adapter

​Frontend Technologies

​Data Flow Patterns

​Wallet Connection Flow

​Data Modes

​Trade Data Pipeline

​State Management

​Connection State

​Persistence Strategy

User Wallets

Trades

Annotations

UI State

​Security & Authentication

​Security Measures

​Local Development

​Performance Considerations

​Optimization Strategies

​Resource Usage

Build docs developers (and LLMs) love

System Overview

Architecture Layers

Component Structure

Technology Stack

Core Framework

Infrastructure

Frontend Technologies

Data Flow Patterns

Wallet Connection Flow

Data Modes

Trade Data Pipeline

State Management

Connection State

Persistence Strategy

Security & Authentication

Security Measures

Local Development

Performance Considerations

Optimization Strategies

Resource Usage