> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> System architecture overview of the OLIVE payment platform

# System Architecture

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

## High-Level Architecture

```mermaid theme={null}
graph TB
    subgraph Clients
        POS[POS Terminals]
        WA[WhatsApp Users]
        Admin[Admin Dashboard]
        API[Third-party APIs]
    end

    subgraph Gateway Layer
        GW[Gateway Service]
        MW[Middleware]
    end

    subgraph Core Services
        Agent[Agent-TS]
        WC[Wallet-Core]
    end

    subgraph Data Layer
        DB[(PostgreSQL)]
        S3[(S3 Storage)]
    end

    subgraph External
        OAI[OpenAI API]
        VULT[VULT Processor]
    end

    POS -->|HTTPS + HMAC| GW
    WA -->|Webhook| Agent
    Admin -->|HTTPS + JWT| GW
    API -->|HTTPS + API Key| GW

    GW --> MW
    MW -->|gRPC + mTLS| WC
    Agent -->|HTTP| GW
    Agent --> OAI

    WC --> DB
    Agent --> S3
    WC --> VULT
```

## Component Overview

### Gateway (Go)

The public-facing REST API that handles all external requests.

| Responsibility  | Description                            |
| --------------- | -------------------------------------- |
| Authentication  | API keys, JWT, HMAC, service auth      |
| Rate Limiting   | Per-client request throttling          |
| Request Routing | Routes to appropriate handlers         |
| Audit Logging   | Comprehensive request/response logging |

### Wallet-Core (Go)

The secure financial engine that processes all transactions.

| Responsibility | Description                       |
| -------------- | --------------------------------- |
| Ledger         | Atomic transaction processing     |
| Accounts       | Multi-currency account management |
| Compliance     | Transaction monitoring and alerts |
| Reconciliation | External processor reconciliation |

### Agent-TS (TypeScript)

AI-powered conversational agent for natural language interactions.

| Responsibility | Description                            |
| -------------- | -------------------------------------- |
| NLU            | OpenAI-powered intent recognition      |
| KYC            | Document validation with OCR           |
| Tools          | Wallet operations via function calling |
| Webhooks       | WhatsApp message handling              |

## Data Flow

### Payment Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant W as Wallet-Core
    participant D as Database

    C->>G: POST /payments
    G->>G: Authenticate & Validate
    G->>W: gRPC: ExecutePayment
    W->>D: BEGIN Transaction
    W->>D: Check Balance
    W->>D: Debit Sender
    W->>D: Credit Recipient
    W->>D: Insert Transaction
    W->>D: Insert Audit Log
    W->>D: COMMIT
    W-->>G: PaymentResponse
    G-->>C: 200 OK
```

### Agent Message Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User (WhatsApp)
    participant A as Agent-TS
    participant O as OpenAI
    participant G as Gateway
    participant W as Wallet-Core

    U->>A: "Check my balance"
    A->>O: Chat Completion
    O-->>A: Function Call: check_balance
    A->>G: GET /balance/{user_id}
    G->>W: gRPC: GetBalance
    W-->>G: Balance Response
    G-->>A: Balance JSON
    A->>O: Function Result
    O-->>A: "Your balance is 5,000 SLE"
    A-->>U: Response Message
```

## Security Layers

<AccordionGroup>
  <Accordion title="Network Layer">
    * VPC isolation for internal services
    * Firewall rules restricting access
    * Network policies in Kubernetes
  </Accordion>

  <Accordion title="Transport Layer">
    * TLS 1.3 for all external traffic
    * mTLS for internal gRPC communication
    * Certificate rotation policies
  </Accordion>

  <Accordion title="Application Layer">
    * JWT/OAuth2 authentication
    * API key management with scopes
    * Rate limiting per client
    * Input validation and sanitization
  </Accordion>

  <Accordion title="Data Layer">
    * Encrypted database connections
    * Comprehensive audit logging
    * Idempotency keys for operations
  </Accordion>
</AccordionGroup>

## Database Schema

### Core Tables

| Table          | Purpose                                  |
| -------------- | ---------------------------------------- |
| `accounts`     | User accounts with balances per currency |
| `transactions` | Central transaction ledger               |
| `subscribers`  | User profiles with KYC status            |
| `nfc_cards`    | Card serials linked to subscribers       |
| `agents`       | Agent/merchant accounts with float       |
| `audit_log`    | Transaction and event audit trail        |
| `api_keys`     | Third-party integration keys             |

### Transaction Table Schema

```sql theme={null}
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
);
```

## Scalability

<CardGroup cols={2}>
  <Card title="Gateway" icon="server">
    Fully stateless, unlimited horizontal scaling behind load balancer
  </Card>

  <Card title="Agent" icon="robot">
    Stateless design with async request handling
  </Card>

  <Card title="Wallet-Core" icon="database">
    Scale with read replicas, sharding by user\_id for writes
  </Card>

  <Card title="Database" icon="table">
    PostgreSQL with connection pooling and optimized indexes
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Gateway Deep Dive" icon="server" href="/gateway/architecture">
    Explore the Gateway architecture in detail
  </Card>

  <Card title="Wallet-Core Ledger" icon="coins" href="/wallet-core/ledger">
    Learn about the transaction processing engine
  </Card>
</CardGroup>