​
System Architecture

Agentik Vault consists of three distinct layers:

Three-Layer System

  1. Frontend — React 19 + Solana wallet integration
  2. Backend — Express.js + PostgreSQL + Docker orchestration
  3. Blockchain — Anchor program on Solana for subscription entitlement

​
Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│  USER (Browser)                                         │
│  1. Connect Solana wallet                               │
│  2. Subscribe to tier (sign Solana transaction)         │
│  3. Deploy agent instance                               │
│  4. Configure API keys                                  │
└────────────────────┬────────────────────────────────────┘
                     │ HTTPS + JWT
                     ↓
┌─────────────────────────────────────────────────────────┐
│  BACKEND (Express.js + PostgreSQL)                      │
│  • Wallet signature authentication (tweetnacl)          │
│  • Subscription verification (cache chain state)        │
│  • Usage enforcement (middleware)                       │
│  • API key encryption (AES-256-GCM)                     │
│  • Docker orchestration (dockerode)                     │
└────────────┬──────────────────┬─────────────────────────┘
             │                  │
             │                  ↓
             │         ┌──────────────────┐
             │         │  Docker Instances │
             │         │  (User Containers)│
             │         └──────────────────┘
             ↓
    ┌────────────────────┐
    │  Solana Blockchain │
    │  (Mainnet-Beta)   │
    │  • Subscription PDAs│
    │  • Payment records │
    └────────────────────┘

​
Frontend Layer

Tech: React 19 + Vite + Tailwind + @solana/react-hooks Key Files: Responsibilities:
  • Wallet connection (auto-discover Phantom, Solflare, etc.)
  • User authentication via signature
  • Subscription management UI
  • Instance provisioning UI

​
Backend Layer

Tech: Express.js + Node 22 + PostgreSQL + dockerode Key Services:
  • subscription.ts — Chain reads + DB cache (TTL 120s)
  • dockerInstance.ts — Container provisioning
  • secureKeyRetrieval.ts — AES-256-GCM encryption
  • usage.ts — Idempotent tracking
Database Schema (PostgreSQL):
  • users — User accounts (wallet → userId mapping)
  • subscriptions — Cached subscription state
  • docker_instances — Running containers
  • api_keys_encrypted — Encrypted user API keys
  • tier_config — Rate limits per tier

​
Blockchain Layer

Tech: Anchor (Rust) + Solana Program ID: F4jZpgbtTb6RWNWq6v35fUeiAsRJMrDczVPv9U23yXjB (mainnet-beta) PDAs: 
subscriptionPDA = derive(["subscription", userWallet])
Subscription struct: 
pub struct Subscription {
    pub owner: Pubkey,
    pub tier: Tier,       // Free, Pro, Enterprise
    pub expires_at: i64,  // Unix timestamp
    pub is_active: bool,
}

​
Critical Principles

​
1. Backend is Authority for Metering

❌ Don’t meter on-chain (too expensive, too slow)
✅ Do cache subscription state in PostgreSQL

​
2. Blockchain is Authority for Entitlement

❌ Don’t trust backend alone for subscription status
✅ Do verify entitlement on-chain, cache for performance

​
3. Encryption at Rest + In Transit

❌ Don’t store plaintext API keys
✅ Do encrypt with AES-256-GCM, decrypt only in user instance

​
Data Flows

​
Authentication Flow

​
Subscription Flow

​
Instance Provisioning Flow

​
Next Steps

Development Setup

Set up local environment and start coding

API Reference

Explore REST API endpoints