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

From	Protocol	Authentication	Format
POS Terminal	HTTPS/REST	HMAC Signature	JSON
Admin Dashboard	HTTPS/REST	JWT Bearer Token	JSON
Third-party API	HTTPS/REST	API Key	JSON
WhatsApp	Webhook	HMAC Verification	JSON

Internal Communication

From	To	Protocol	Authentication
Gateway	Wallet-Core	gRPC	mTLS
Agent-TS	Gateway	HTTPS	Service Auth
Agent-TS	OpenAI	HTTPS	API Key

Data Flow Patterns

Payment Request Flow

Request Received

Client sends payment request to Gateway (HTTPS + Auth)

Authentication

Gateway validates API key, JWT, or HMAC signature

Rate Limiting

Request checked against rate limits

Forward to Core

Gateway calls Wallet-Core via gRPC

Transaction Execution

Wallet-Core executes atomic DB transaction

Audit Logging

Transaction logged to audit table

Response

Success/failure returned through the chain

Agent Conversation Flow

Database Schema

Core Tables

Table	Purpose	Key Fields
`accounts`	User balances per currency	`user_id`, `currency`, `balance`
`transactions`	Central ledger	`request_id`, `amount`, `status`
`subscribers`	User profiles + KYC	`phone`, `kyc_level`, `status`
`nfc_cards`	Card-subscriber mapping	`serial`, `subscriber_id`
`agents`	Agent float accounts	`phone`, `float_balance`
`audit_log`	Transaction events	`transaction_id`, `event_type`
`api_keys`	Integration keys	`key_hash`, `scopes`

Schema Details

Accounts Table

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)
);

Transactions Table

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
);

Audit Log Table

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:

Client generates unique UUID for request_id
Wallet-Core checks for existing transaction with that ID
If found, returns cached result (no duplicate execution)
If not found, executes transaction
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

Component	Failure Impact	Recovery Strategy
Gateway	Client requests fail	Load balancer routes to healthy instances
Wallet-Core	Payments fail	Backup instance, transaction rollback
Agent-TS	WhatsApp bot offline	Restart, conversation continues
Database	All services down	Restore 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

​Architecture Reference

​System Components

Gateway

Wallet-Core

Agent-TS

​High-Level Architecture

​Communication Protocols

​External to Gateway

​Internal Communication

​Data Flow Patterns

​Payment Request Flow

​Agent Conversation Flow

​Database Schema

​Core Tables

​Schema Details

​Idempotency

​Error Handling

​Gateway Errors

​Wallet-Core Errors

​Agent Errors

​Scalability

Horizontal Scaling

Vertical Scaling

​Database Scaling Options

​Failure Modes

​Related

Gateway Architecture

Wallet-Core Ledger

Security Reference

Deployment Guide

Architecture Reference

System Components

High-Level Architecture

Communication Protocols

External to Gateway

Internal Communication

Data Flow Patterns

Payment Request Flow

Agent Conversation Flow

Database Schema

Core Tables

Schema Details

Idempotency

Error Handling

Gateway Errors

Wallet-Core Errors

Agent Errors

Scalability

Database Scaling Options

Failure Modes

Related