Skip to main content

​
Architecture Reference

OLIVE is a three-tier payment processing system designed for high security, scalability, and AI-powered decision making.

​
System Components

Gateway

Go + GinPublic REST API, authentication, rate limiting

Wallet-Core

Go + gRPCFinancial engine, ledger, ACID transactions

Agent-TS

TypeScript + OpenAIConversational AI, WhatsApp integration

​
High-Level Architecture

​
Communication Protocols

​
External to Gateway

FromProtocolAuthenticationFormat
POS TerminalHTTPS/RESTHMAC SignatureJSON
Admin DashboardHTTPS/RESTJWT Bearer TokenJSON
Third-party APIHTTPS/RESTAPI KeyJSON
WhatsAppWebhookHMAC VerificationJSON

​
Internal Communication

FromToProtocolAuthentication
GatewayWallet-CoregRPCmTLS
Agent-TSGatewayHTTPSService Auth
Agent-TSOpenAIHTTPSAPI Key

​
Data Flow Patterns

​
Payment Request Flow

1

Request Received

Client sends payment request to Gateway (HTTPS + Auth)
2

Authentication

Gateway validates API key, JWT, or HMAC signature
3

Rate Limiting

Request checked against rate limits
4

Forward to Core

Gateway calls Wallet-Core via gRPC
5

Transaction Execution

Wallet-Core executes atomic DB transaction
6

Audit Logging

Transaction logged to audit table
7

Response

Success/failure returned through the chain

​
Agent Conversation Flow

​
Database Schema

​
Core Tables

TablePurposeKey Fields
accountsUser balances per currencyuser_id, currency, balance
transactionsCentral ledgerrequest_id, amount, status
subscribersUser profiles + KYCphone, kyc_level, status
nfc_cardsCard-subscriber mappingserial, subscriber_id
agentsAgent float accountsphone, float_balance
audit_logTransaction eventstransaction_id, event_type
api_keysIntegration keyskey_hash, scopes

​
Schema Details

CREATE TABLE accounts (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    currency TEXT NOT NULL,
    balance INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    UNIQUE(user_id, currency)
);

CREATE TABLE transactions (
    id TEXT PRIMARY KEY,
    request_id TEXT UNIQUE NOT NULL,
    user_id TEXT NOT NULL,
    recipient_id TEXT NOT NULL,
    amount INTEGER NOT NULL,
    currency TEXT NOT NULL,
    status TEXT NOT NULL,
    memo TEXT,
    metadata JSONB,
    created_at TIMESTAMP,
    completed_at TIMESTAMP
);

CREATE TABLE audit_log (
    id SERIAL PRIMARY KEY,
    transaction_id TEXT NOT NULL,
    event_type TEXT NOT NULL,
    actor TEXT,
    details JSONB,
    timestamp TIMESTAMP DEFAULT NOW()
);

​
Idempotency

All payment operations are idempotent using request_id:
  1. Client generates unique UUID for request_id
  2. Wallet-Core checks for existing transaction with that ID
  3. If found, returns cached result (no duplicate execution)
  4. If not found, executes transaction
  5. Result cached for idempotency window (24 hours default)
Always generate unique request_id values. Duplicate IDs will return the original transaction instead of creating a new one.

​
Error Handling

​
Gateway Errors

  • Input validation with detailed error messages
  • Standard HTTP status codes
  • Sanitized error responses (no internal details)
  • All errors logged with request context

​
Wallet-Core Errors

  • Automatic transaction rollback on any failure
  • gRPC error codes with structured details
  • Database consistency guaranteed

​
Agent Errors

  • Graceful degradation to safe defaults
  • Timeout protection for OpenAI calls
  • Policy violations logged but non-fatal

​
Scalability

Horizontal Scaling

  • Gateway: Unlimited instances behind load balancer
  • Agent-TS: Stateless, unlimited scaling
  • Wallet-Core: Limited by database connections

Vertical Scaling

  • Increase memory for caching
  • Database optimization with indexes
  • Connection pooling tuning

​
Database Scaling Options

  • Read replicas for balance queries and reporting
  • Connection pooling with PgBouncer
  • Partitioning by date for transaction history
  • Sharding by user_id for write distribution

​
Failure Modes

ComponentFailure ImpactRecovery Strategy
GatewayClient requests failLoad balancer routes to healthy instances
Wallet-CorePayments failBackup instance, transaction rollback
Agent-TSWhatsApp bot offlineRestart, conversation continues
DatabaseAll services downRestore from backup, point-in-time recovery

Gateway Architecture

Detailed Gateway internals

Wallet-Core Ledger

Transaction processing details

Security Reference

Security configuration

Deployment Guide

Production deployment