System overview

High-level architecture of the CAIVEMEN platform.

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                     Solana Blockchain                       │
└────────────────┬────────────────────────────────────────────┘
                 │ Real-time transactions
                 ↓
┌─────────────────────────────────────────────────────────────┐
│                   Helius gRPC Stream                        │
│            (laserstream-mainnet-fra.helius-rpc.com)        │
└────────────────┬────────────────────────────────────────────┘
                 │ Millisecond latency
                 ↓
┌─────────────────────────────────────────────────────────────┐
│                    CAIVEMEN Backend (Rust)                  │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │  Transaction Parser                                     │ │
│ │  - Classify type (buy/sell/transfer)                   │ │
│ │  - Classify size (small/medium/large)                  │ │
│ │  - Extract wallet & amount                             │ │
│ └────────────┬────────────────────────────────────────────┘ │
│              ↓                                               │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  Event Generator                                       │  │
│ │  - Map transaction → world effect                     │  │
│ │  - Spawn food/disasters                                │  │
│ │  - Update tension                                      │  │
│ └────────────┬─────────────────────────────────────────────┘ │
│              ↓                                               │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  Game State Manager                                    │  │
│ │  - Central state (cavemen, food, disasters)           │  │
│ │  - Position updates                                    │  │
│ │  - Combat resolution                                   │  │
│ │  - Death/respawn logic                                 │  │
│ └────────────┬─────────────────────────────────────────────┘ │
│              ↓                                               │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  AI Decision Engine (every 3s)                         │  │
│ │  - Build prompts for each caveman                      │  │
│ │  - Call OpenRouter LLM APIs in parallel                │  │
│ │  - Parse JSON responses                                 │  │
│ │  - Execute actions (move/attack/flee/eat)              │  │
│ └────────────┬─────────────────────────────────────────────┘ │
│              ↓                                               │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  Game Loop (every 100ms)                               │  │
│ │  - Apply hunger/health changes                         │  │
│ │  - Process disaster damage                             │  │
│ │  - Update respawn timers                               │  │
│ │  - Clamp positions                                     │  │
│ └────────────┬─────────────────────────────────────────────┘ │
└──────────────┼────────────────────────────────────────────┘
               │
               ├────────────┐
               ↓            ↓
┌──────────────────┐  ┌──────────────────────────────┐
│  WebSocket       │  │  Firestore                   │
│  Broadcast       │  │  (Persistent Storage)        │
│  (every 200ms)   │  │  - Events                    │
└────┬─────────────┘  │  - Transactions              │
     │                │  - Kills                     │
     │                │  - Stats                     │
     │                │  - Disasters                 │
     │                └──────────────────────────────┘
     ↓
┌─────────────────────────────────────────────────────────────┐
│              Next.js Frontend (React + Canvas)              │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │  WebSocket Client                                       │ │
│ │  - Receive state updates                                │ │
│ │  - Handle reconnection                                  │ │
│ └────────────┬────────────────────────────────────────────┘ │
│              ↓                                               │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  State Management                                       │  │
│ │  - Store current game state                            │  │
│ │  - Smooth position interpolation (lerp)                │  │
│ │  - Click detection for caveman selection               │  │
│ └────────────┬────────────────────────────────────────────┘ │
│              ↓                                               │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  Canvas Renderer (60 FPS)                              │  │
│ │  - Draw terrain (rivers, forests)                      │  │
│ │  - Draw cavemen with smooth movement                   │  │
│ │  - Draw food & disasters                               │  │
│ │  - Health bars & name labels                           │  │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐  │
│ │  UI Components                                          │  │
│ │  - Event log (real-time feed)                          │  │
│ │  - Stats panel (kills, health)                         │  │
│ │  - Selected caveman details                            │  │
│ └─────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
               │
               ↓
         Browser (User)

Core Components

Backend Stack

• Language: Rust

• Runtime: Tokio (async)

• Framework: Axum (WebSocket server)

Dependencies:

• tonic - gRPC client for Helius

• tokio - Async runtime

• axum - HTTP/WebSocket server

• firebase-admin - Firestore SDK

• serde - JSON serialization

Frontend Stack

• Framework: Next.js 15

• Runtime: Bun

• Rendering: HTML5 Canvas

Dependencies:

• react - UI framework

• next - SSR framework

• bun - JavaScript runtime

Data Flow Paths

1

Transaction → World Effect

• Helius gRPC sends transaction (~10ms from blockchain)

• Parser classifies transaction (~1ms)

• Event generator creates world effect (~1ms)

• Game state mutates (~1ms)

• WebSocket broadcasts to frontend (~5ms)

• Frontend renders update (~16ms @ 60fps)

Total latency: ~35ms from blockchain to screen

2

AI Decision Loop

• Timer fires every 3000ms

• Build prompts for all 5 cavemen (~10ms)

• Call OpenRouter APIs in parallel (~500-2000ms)

• Parse JSON responses (~5ms)

• Execute actions & update state (~10ms)

• Firestore logs events asynchronously

• WebSocket broadcasts immediately

• Frontend renders within 16ms

Total cycle: ~3.5-5 seconds including LLM latency

3

Game Loop

• Timer fires every 100ms

• Update hunger (+0.05% per caveman)

• Update health (regen if conditions met)

• Process disaster damage

• Update respawn timers

• Clamp positions to bounds

• Check for starvation deaths

Processing time: <5ms for 5 cavemen