> ## 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.

# Overview

> Secure financial engine for the OLIVE payment platform

# Wallet-Core Overview

Wallet-Core is the authoritative financial engine for OLIVE, managing accounts, executing payments and transfers, enforcing compliance, logging audits, and integrating with external processors.

## Purpose

<CardGroup cols={2}>
  <Card title="Ledger" icon="coins">
    Atomic transaction processing with database transactions and audit logs
  </Card>

  <Card title="Accounts" icon="credit-card">
    Multi-currency account management with balance tracking
  </Card>

  <Card title="Compliance" icon="shield-check">
    Transaction monitoring, alerts, and compliance rules
  </Card>

  <Card title="Reconciliation" icon="scale-balanced">
    External processor reconciliation with VULT
  </Card>
</CardGroup>

## Who Uses It

| Client          | Protocol | Use Case                |
| --------------- | -------- | ----------------------- |
| Gateway         | gRPC     | All API operations      |
| Background Jobs | Direct   | Reconciliation, cleanup |
| Admin Tools     | gRPC     | Reporting, maintenance  |

## Key Features

### Atomic Transactions

All financial operations are atomic with database transactions:

```go theme={null}
// Simplified transaction flow
tx, _ := db.Begin()

// Debit sender
tx.Exec("UPDATE accounts SET balance = balance - $1 WHERE user_id = $2", amount, senderID)

// Credit recipient  
tx.Exec("UPDATE accounts SET balance = balance + $1 WHERE user_id = $2", amount, recipientID)

// Insert transaction record
tx.Exec("INSERT INTO transactions (...) VALUES (...)")

// Insert audit log
tx.Exec("INSERT INTO audit_log (...) VALUES (...)")

tx.Commit()
```

### Idempotency

All payments support idempotency via `request_id`:

```protobuf theme={null}
message PaymentRequest {
  string request_id = 1;  // Client-provided unique ID
  string user_id = 2;
  string recipient_id = 3;
  int64 amount = 4;
  string currency = 5;
}
```

If a duplicate `request_id` is received, the existing transaction is returned.

### Account Model

Accounts are stored per user and currency:

```sql theme={null}
CREATE TABLE accounts (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  currency TEXT NOT NULL,
  balance BIGINT NOT NULL DEFAULT 0,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  UNIQUE(user_id, currency)
);
```

## gRPC Services

Wallet-Core exposes multiple gRPC services:

| Service             | Purpose                                |
| ------------------- | -------------------------------------- |
| `WalletService`     | Core: payments, balances, transactions |
| `SubscriberService` | User registration and management       |
| `CardService`       | NFC card operations                    |
| `AgentService`      | Agent/merchant operations              |
| `ComplianceService` | Monitoring and alerts                  |
| `POSService`        | POS terminal operations                |
| `AuditService`      | Audit log operations                   |
| `APIKeyService`     | API key management                     |
| `ProcessorService`  | External processor integration         |
| `PEPAccessService`  | Privileged access flows                |

## Quick Start

### With Docker Compose

```bash theme={null}
docker compose up -d --build wallet-core
```

### Build and Run Locally

```bash theme={null}
cd wallet-core
go build -o wallet-core ./cmd/server
./wallet-core -config config.yaml
```

### Test gRPC Connectivity

```bash theme={null}
grpcurl -plaintext localhost:50051 wallet.WalletService/HealthCheck
```

## Architecture

```mermaid theme={null}
graph TB
    subgraph External
        GW[Gateway]
    end

    subgraph "Wallet-Core"
        SRV[gRPC Server]
        
        subgraph Services
            SS[Subscriber Service]
            CS[Card Service]
            AS[Agent Service]
            WS[Wallet Service]
            CPS[Compliance Service]
        end
        
        LED[Ledger]
        
        subgraph Repositories
            SR[Subscriber Repo]
            CR[Card Repo]
            AR[Account Repo]
            TR[Transaction Repo]
        end
    end

    subgraph Data
        DB[(PostgreSQL)]
    end

    GW -->|gRPC| SRV
    SRV --> SS & CS & AS & WS & CPS
    SS & CS & AS --> LED
    WS --> LED
    LED --> AR & TR
    SS --> SR
    CS --> CR
    SR & CR & AR & TR --> DB
```

## Project Structure

```
wallet-core/
├── cmd/
│   ├── server/
│   │   └── main.go       # Entry point
│   └── tools/            # CLI utilities
├── internal/
│   ├── config/           # Configuration loading
│   ├── database/         # DB connection & migrations
│   ├── ledger/           # Core transaction engine
│   ├── models/           # Domain models
│   ├── repository/       # Data access layer
│   ├── server/           # gRPC server adapters
│   └── services/         # Business logic (16 services)
├── pkg/                  # Shared packages
├── config.yaml           # Default configuration
└── Dockerfile
```

## Data Model

### Core Tables

| Table          | Purpose             | Key Fields                  |
| -------------- | ------------------- | --------------------------- |
| `subscribers`  | User profiles       | phone, kyc\_level           |
| `accounts`     | Balance by currency | user\_id, currency, balance |
| `transactions` | Transaction ledger  | request\_id, amount, status |
| `nfc_cards`    | Card mappings       | serial, subscriber\_id      |
| `agents`       | Agent accounts      | float\_balance              |
| `audit_log`    | Event audit trail   | event\_type, timestamp      |

### Transaction Statuses

| Status      | Description            |
| ----------- | ---------------------- |
| `PENDING`   | Transaction initiated  |
| `COMPLETED` | Successfully processed |
| `FAILED`    | Processing failed      |
| `REVERSED`  | Transaction reversed   |

## Security

* **gRPC TLS**: Enable for production environments
* **mTLS**: Mutual TLS between Gateway and Wallet-Core
* **Audit Logging**: All operations logged
* **Access Control**: Service-level authentication

## Next Steps

<CardGroup cols={2}>
  <Card title="Ledger" icon="coins" href="/wallet-core/ledger">
    Transaction processing details
  </Card>

  <Card title="Architecture" icon="sitemap" href="/wallet-core/architecture">
    Internal architecture
  </Card>

  <Card title="Configuration" icon="gear" href="/wallet-core/configuration">
    config.yaml reference
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete endpoint docs
  </Card>
</CardGroup>