How It Works

​

System Architecture

​

High-Level Flow

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│ IDL Upload  │ ──▶ │ IDL Parsing  │ ──▶ │ API Generation  │ ──▶ │ Transaction      │
│             │     │ & Validation │     │ & Documentation │     │ Building         │
└─────────────┘     └──────────────┘     └─────────────────┘     └──────────────────┘

1. IDL Upload: User uploads an Anchor IDL JSON file via the dashboard
2. IDL Parsing: System validates the IDL structure and extracts metadata
3. API Generation: RESTful endpoints are automatically created for each instruction
4. Transaction Building: Users call endpoints with parameters to build Solana transactions

​

Component Architecture

​

Frontend (React SPA)

• Stack: React 18 + TypeScript + Tailwind CSS + Vite
• Deployment: Cloudflare Pages (static + dynamic assets)
• Features:
  • GitHub OAuth authentication
  • IDL upload & project management
  • API key management
  • Usage analytics dashboard
  • Interactive API explorer

​

Backend (Hono + Workers)

• Stack: Hono + TypeScript + Cloudflare Workers
• Runtime: Cloudflare Workers (V8 Edge Runtime)
• Features:
  • RESTful API endpoints
  • IDL parsing and validation
  • Transaction building engine
  • Markdown documentation generation
  • GitHub OAuth integration

​

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                     End Users                               │
└─────────────┬───────────────────────────────────────────────┘
              │
    ┌─────────┴──────────┐
    │                    │
┌───▼──────────┐   ┌─────▼───────────┐
│   Frontend   │   │   API Explorer  │
│ (React SPA)  │   │   & Dashboard   │
└──────┬───────┘   └─────────┬───────┘
       │                     │
       └──────────┬──────────┘
                  │
     ┌────────────▼────────────────────┐
     │  Cloudflare Workers (Hono)      │
     │  ──────────────────────────────  │
     │  - Auth (GitHub OAuth)          │
     │  - IDL Management               │
     │  - Transaction Building         │
     │  - Documentation Generation     │
     └────────┬───────────┬────────────┘
              │           │
     ┌────────▼───────────▼─────────┐
     │  Cloudflare Infrastructure   │
     │  D1 │ KV │ Cache │ HTTP/2    │
     └────────┬───────────┬─────────┘
              │           │
     ┌────────▼───────────▼─────────┐
     │  Solana RPC Endpoints        │
     │  (devnet, testnet, mainnet)  │
     └──────────────────────────────┘

​

Edge Deployment

​

Why Cloudflare Workers?

• Global Edge Network: Code runs in 300+ data centers worldwide
• Automatic Scaling: Handles millions of requests without configuration
• Zero Cold Starts: Workers start in less than 1ms
• Cost Effective: Pay only for actual usage
• Integrated Storage: D1 database and KV store built-in

​

Data Storage

​

D1 Database (SQLite)

• users: Authenticated user accounts
• projects: Solana programs/projects
• idl_versions: IDL version history
• api_keys: API credentials for private projects
• project_socials: Project metadata and social links

​

KV Store (Key-Value)

• IDL Cache: idl:{projectId}:{version} (TTL: 1 week)
• General Cache: cache:{type}:{id} (variable TTL)

​

Request Flow

​

Authentication Flow

User → GitHub OAuth → Worker Auth Handler → JWT Token → Frontend Storage

1. User clicks “Sign in with GitHub”
2. Redirects to GitHub OAuth authorization
3. GitHub redirects to /auth/github/callback with code
4. Worker exchanges code for access token
5. Fetches user data from GitHub API
6. Creates/updates user in D1 database
7. Returns JWT token (7-day expiration)
8. Frontend stores token in localStorage
9. Includes token in Authorization header for requests

​

Transaction Building Flow

User → Input Data → POST /build → Parse Inputs → Build IX → Serialize TX

1. User provides instruction name, accounts, and arguments
2. Sends POST to /api/{projectId}/instructions/{name}/build
3. Worker validates request data against IDL schema
4. Derives PDAs if needed from seed templates
5. Constructs Solana instruction with data
6. Builds transaction with recent blockhash
7. Serializes to base58 format
8. Returns serialized transaction + metadata

​

Performance Optimizations

​

Caching Strategy

1. KV Cache: IDL and docs cached for 1 week
2. HTTP Cache: Static assets cached for 1 year (immutable)
3. Browser Cache: JS/CSS bundles with content hashing
4. Database Query Cache: Frequently accessed data memoized

​

Load Reduction

• Code Splitting: Vite splits JS into route-based chunks
• Asset Compression: Automatic gzip/brotli compression
• Lazy Loading: Pages and components loaded on demand
• Image Optimization: Cloudflare Image Resize for avatars

​

Scalability

​

Horizontal Scaling

• Workers: Automatically scale across Cloudflare’s network
• D1: Distributed database scales with usage
• KV: Globally distributed key-value store

​

Rate Limiting

• Per IP per endpoint (100 req/min)
• Per API key for private projects (1000 req/hr)
• Per user account (500 req/min)

​

Development Workflow

​

Local Development

# Start frontend dev server (Vite)
npm run dev:frontend

# Start worker dev server (Wrangler)
npm run dev:worker

​

Building & Deployment

# Type checking and linting
npm run typecheck
npm run lint

# Build all packages
npm run build

# Deploy worker to Cloudflare
npm run deploy:worker

# Deploy frontend to Cloudflare Pages
npm run deploy:frontend