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

# Platform Architecture

> Technical overview of how the Atlas platform is built — from event ingestion to analytics delivery.

## High-Level Architecture

The Atlas platform is a microservices-based system with four primary layers:

```
┌──────────────────────────────────────────────────────────┐
│                   CLIENT LAYER                           │
│  Your Backend  │  Your Frontend  │  Atlas Dashboard      │
└───────┬────────────────┬──────────────────┬──────────────┘
        │ Events API     │ SDK JS           │ Web App
        ▼                ▼                  ▼
┌──────────────────────────────────────────────────────────┐
│                   INGESTION LAYER                        │
│           Atlas Events API (Go + Fiber)                  │
│    POST /api/v1/{user,transaction,casino,sport}          │
└───────────────────────┬──────────────────────────────────┘
                        │ Publish
                        ▼
┌──────────────────────────────────────────────────────────┐
│                   STREAMING LAYER                        │
│              Apache Kafka                                │
│   Topics: atlas.events.raw · atlas.events.dlq            │
│           Per-type topics (domain events)                │
└───────────────────────┬──────────────────────────────────┘
                        │ Consume
                        ▼
┌──────────────────────────────────────────────────────────┐
│                   PROCESSING LAYER                       │
│   Financial Engine  │  Risk Engine  │  Compliance Engine │
│   Behavior Analysis │  ML Models    │  PLD Monitoring    │
└───────────────────────┬──────────────────────────────────┘
                        │ Persist + Serve
                        ▼
┌──────────────────────────────────────────────────────────┐
│                   DELIVERY LAYER                         │
│   Backend API (Go)  │  Dashboard (Next.js)               │
│   Webhooks          │  Report Exports                    │
└──────────────────────────────────────────────────────────┘
```

## Services

### Events API (`atlas-events`)

The high-throughput event ingestion service. Its only job is to receive events and publish them to Kafka as fast as possible.

| Property      | Value                         |
| ------------- | ----------------------------- |
| Language      | Go 1.24                       |
| Framework     | Fiber v2                      |
| Message Queue | Kafka (kafka-go)              |
| Throughput    | 1,000+ req/s per instance     |
| Latency       | \< 5ms p99 (publish to Kafka) |

**Architectural layers:**

```
HTTP Request
    │
    ▼
Middleware (RequestID → Logger → Recover → Timeout)
    │
    ▼
Handler (Fiber) — validates DTO, extracts brand/org context
    │
    ▼
Service — business logic, event enrichment
    │
    ├──► Kafka Producer (primary topic)
    │
    └──► DLQ Producer (on publish failure)
```

**Failure handling:** If Kafka is unavailable, events are routed to the Dead-Letter Queue (`atlas.events.dlq`) for replay. This ensures zero data loss under normal infrastructure failures.

### Backend API (`atlas-backend`)

The application backend — handles authentication, user management, multi-tenancy, and data serving for the dashboard.

| Property      | Value                                   |
| ------------- | --------------------------------------- |
| Language      | Go 1.24                                 |
| Framework     | net/http                                |
| Database      | PostgreSQL 17                           |
| Auth          | Auth0 (JWT + Google OAuth)              |
| Multi-tenancy | Per-organization with role-based access |

### Dashboard (`atlas-web`)

The main frontend application for operators and analysts.

| Property   | Value                      |
| ---------- | -------------------------- |
| Framework  | Next.js 16                 |
| Language   | TypeScript                 |
| Styling    | Tailwind CSS 4 + shadcn/ui |
| Deployment | Cloudflare Pages           |

## Data Flow: A Bet Being Placed

1. Player places a bet on your platform
2. Your backend calls `POST /api/v1/sport` with the bet details
3. Events API validates the payload and publishes to the `atlas.events.raw.sportsbook` Kafka topic
4. Kafka consumers process the event: update risk exposure, financial position, player profile
5. Analytics are immediately available in the Atlas Dashboard
6. If a risk threshold is exceeded, a webhook fires to your system (coming soon)

## Kafka Topics

| Topic                          | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| `atlas.events.raw`             | Generic events (used with `/v1/events` endpoint)  |
| `atlas.events.raw.user`        | User registration and profile update events       |
| `atlas.events.raw.transaction` | Deposit and withdrawal events                     |
| `atlas.events.raw.casino`      | Casino `open`, `win` and `lose` events            |
| `atlas.events.raw.sportsbook`  | Sports `open`, `win`, `lose` and `cashout` events |
| `atlas.events.dlq`             | Dead-letter queue — failed publish events         |

## Security Model

* **Events API**: API Key authentication (`X-API-Key` header) for domain endpoints, JWT Bearer for generic events
* **Backend API**: Auth0-issued JWT tokens with organization scope
* **Data Isolation**: All data is scoped by `org_id` + `brand_id`. Cross-tenant access is impossible at the data layer.
* **TLS**: All endpoints enforce HTTPS in production

## Infrastructure

```
                    Cloudflare (CDN + DDoS protection)
                             │
              ┌──────────────┴──────────────┐
              │                             │
        atlas-events                   atlas-backend
        (Go + Fiber)                  (Go + net/http)
              │                             │
              ▼                             ▼
           Kafka                       PostgreSQL 17
        (KRaft mode)               (connection pooling via pgx)
```