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

> REST API Gateway for the OLIVE payment platform

# Gateway Overview

The OLIVE Gateway is a Go-based REST API that serves as the public entry point for all external integrations. It handles authentication, rate limiting, request routing, and proxies requests to the wallet-core service over gRPC.

## Purpose

<CardGroup cols={2}>
  <Card title="API Surface" icon="code">
    REST endpoints for payments, subscribers, cards, agents, compliance, and admin operations
  </Card>

  <Card title="Authentication" icon="key">
    Multiple auth methods: API keys, JWT, HMAC, service auth
  </Card>

  <Card title="Security" icon="shield">
    Rate limiting, input validation, audit logging, and CORS protection
  </Card>

  <Card title="Observability" icon="chart-line">
    Structured logging, Prometheus metrics, and Swagger documentation
  </Card>
</CardGroup>

## Who Uses It

| Client                   | Authentication    | Use Case                        |
| ------------------------ | ----------------- | ------------------------------- |
| External POS             | HMAC per-merchant | Terminal payments               |
| WhatsApp Agent           | Service auth      | User operations via chat        |
| Admin Dashboard          | JWT               | User and transaction management |
| Third-party Integrations | API Keys          | Partner integrations            |

## Endpoint Groups

### Public Endpoints

| Endpoint                          | Description                           |
| --------------------------------- | ------------------------------------- |
| `GET /health`                     | Gateway and wallet-core health status |
| `GET /version`                    | API version information               |
| `POST /api/v1/public/subscribers` | Public subscriber registration        |

### Protected Endpoints

| Group       | Endpoints                        | Auth Required |
| ----------- | -------------------------------- | ------------- |
| Subscribers | Register, lookup, update, block  | API Key / JWT |
| Cards       | Link, block, unblock, upload CSV | API Key / JWT |
| Wallet      | Balance, payments, transfers     | API Key / JWT |
| Agents      | Lookup, cashin, transfer         | API Key / JWT |
| POS         | Payment, verify-card             | HMAC          |
| Compliance  | Check, alerts, rules             | JWT (Admin)   |
| Admin       | Login, API keys, audit logs      | JWT           |
| Webhooks    | VULT cashin                      | HMAC          |

## Quick Start

### With Docker Compose

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

### Build and Run Locally

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

### Verify Health

```bash theme={null}
curl http://localhost:8080/health
```

Expected response:

```json theme={null}
{
  "service": "gateway",
  "version": "1.0.0",
  "healthy": true,
  "wallet_core": {
    "healthy": true,
    "version": "1.0.0"
  }
}
```

## API Documentation

Interactive Swagger documentation is available at:

```
http://localhost:8080/docs
```

## Architecture

```mermaid theme={null}
graph LR
    subgraph Clients
        POS[POS Terminal]
        Agent[Agent-TS]
        Admin[Admin UI]
        API[Third-party]
    end

    subgraph Gateway
        MW[Middleware Stack]
        H[Handlers]
        WC[Wallet Client]
    end

    subgraph Backend
        WCore[Wallet-Core]
        DB[(PostgreSQL)]
    end

    POS -->|HMAC| MW
    Agent -->|Service Auth| MW
    Admin -->|JWT| MW
    API -->|API Key| MW

    MW --> H
    H --> WC
    WC -->|gRPC| WCore
    WCore --> DB
```

## Project Structure

```
gateway/
├── cmd/
│   └── server/
│       └── main.go          # Entry point, route registration
├── internal/
│   ├── auth/                # JWT, API key validation
│   ├── config/              # YAML config loading
│   ├── handler/             # HTTP handlers (17 files)
│   │   ├── subscriber_handler.go
│   │   ├── card_handler.go
│   │   ├── wallet_handler.go
│   │   ├── agent_handler.go
│   │   ├── pos_handler.go
│   │   ├── compliance_handler.go
│   │   └── ...
│   ├── middleware/          # Auth, logging, rate limiting (12 files)
│   ├── utils/               # Helpers and utilities
│   └── wallet/              # gRPC client wrapper
├── docs/                    # Swagger generated docs
├── config.yaml              # Default configuration
└── Dockerfile
```

## Key Features

### Idempotent Operations

All payment requests support idempotency via `X-Request-ID` header:

```bash theme={null}
curl -X POST http://localhost:8080/api/v1/payments \
  -H "Authorization: Bearer API_KEY" \
  -H "X-Request-ID: unique-request-123" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "u123", "recipient": "u456", "amount": 5000}'
```

### Audit Logging

All operations are logged with:

* Request/response details
* User and client identification
* Timestamps and duration
* Operation outcomes

### Error Responses

Standard error format:

```json theme={null}
{
  "error": "Error description",
  "code": "ERROR_CODE",
  "details": {}
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/gateway/authentication">
    Configure API keys, JWT, and HMAC
  </Card>

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

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

  <Card title="Architecture" icon="sitemap" href="/gateway/architecture">
    Internal architecture details
  </Card>
</CardGroup>