# nutcas3/lets-bet architecture

> Architecture diagram of the GitHub repository nutcas3/lets-bet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nutcas3/lets-bet
- Repository: https://github.com/nutcas3/lets-bet

## Overview

This is a multi-country betting platform whose documented user journey spans sports odds and bet placement, wallet funding, game play, and settlement. The repository separates HTTP/service entry points, country-specific payment adapters, core use cases, and shared infrastructure. The sampled code confirms the odds engine’s provider/cache/event flow and the crash-game engine’s dependencies; the README supplies the broader product capabilities and service architecture. Some documented flows have no sampled implementation excerpt, so their links are shown only where the README explicitly describes them.

Main entry points: [`internal/core/usecase/odds/engine.go`](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/odds/engine.go) (Odds engine), [`internal/core/usecase/games/crash_engine.go`](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/games/crash_engine.go) (Crash game engine), [`cmd/gateway/main.go`](https://github.com/nutcas3/lets-bet/blob/main/cmd/gateway/main.go) (API gateway), [`internal/tenant/ke/mpesa.go`](https://github.com/nutcas3/lets-bet/blob/main/internal/tenant/ke/mpesa.go) (Country payment adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Service entry points"]
  node_gateway["API gateway<br/>[main.go]"]
  node_engine["Betting engine<br/>[main.go]"]
  node_games_service["Games service<br/>[main.go]"]
  node_wallet_service["Wallet service<br/>[main.go]"]
  node_settlement_service["Settlement service<br/>[main.go]"]
end

subgraph group_domain["Betting and games"]
  node_sports_http["Sports HTTP<br/>[engine_handlers.go]"]
  node_bet_placement["Bet placement<br/>[place_bet.go]"]
  node_odds_engine["Odds engine<br/>[engine.go]"]
  node_sports_live["Live sports<br/>[service.go]"]
  node_crash_engine["Crash game engine<br/>[crash_engine.go]"]
  node_fairness["Provably fair<br/>[provably_fair.go]"]
end

subgraph group_money["Wallet and compliance"]
  node_wallet_logic["Wallet operations<br/>[wallet.go]"]
  node_tax["Tax calculations<br/>[tax.go]"]
  node_payments["Country payment adapters<br/>[mpesa.go]"]
  node_compliance["BCLB compliance<br/>[service.go]"]
  node_kyc["Smile ID KYC<br/>[smileid.go]"]
end

subgraph group_infra["Shared infrastructure"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis cache<br/>[odds_cache.go]")]
  node_event_bus["NATS event bus<br/>[bus.go]"]
end

node_bettor(("Bettor"))
node_odds_provider["Sports odds feeds"]
node_payment_networks["Payment networks"]
node_identity_provider["Identity provider"]

node_bettor -->|"submits requests"| node_gateway
node_bettor -->|"plays crash game"| node_games_service
node_gateway -.->|"routes betting"| node_engine
node_gateway -.->|"routes wallet"| node_wallet_service
node_gateway -.->|"routes game"| node_games_service
node_engine -->|"registers routes"| node_sports_http
node_sports_http -->|"handles odds"| node_odds_engine
node_bet_placement -->|"applies tax"| node_tax
node_bet_placement -->|"reserves funds"| node_wallet_logic
node_bet_placement -.->|"persists bet"| node_postgres
node_odds_engine -->|"fetches odds"| node_odds_provider
node_odds_engine -->|"caches odds"| node_redis
node_odds_engine -->|"publishes updates"| node_event_bus
node_odds_engine -->|"reads odds"| node_redis
node_sports_live -.->|"retrieves events"| node_odds_provider
node_games_service -->|"starts engine"| node_crash_engine
node_crash_engine -->|"generates outcomes"| node_fairness
node_crash_engine -->|"uses wallet"| node_wallet_logic
node_crash_engine -->|"uses tax"| node_tax
node_crash_engine -.->|"stores game data"| node_postgres
node_wallet_service -.->|"initiates payment"| node_payments
node_payments -.->|"requests transfer"| node_payment_networks
node_payment_networks -.->|"sends callback"| node_payments
node_payments -.->|"credits wallet"| node_wallet_logic
node_compliance -.->|"requests verification"| node_kyc
node_kyc -->|"verifies identity"| node_identity_provider
node_settlement_service -.->|"reads bet records"| node_postgres
node_settlement_service -.->|"pays winners"| node_wallet_logic

click node_gateway "https://github.com/nutcas3/lets-bet/blob/main/cmd/gateway/main.go"
click node_engine "https://github.com/nutcas3/lets-bet/blob/main/cmd/engine/main.go"
click node_games_service "https://github.com/nutcas3/lets-bet/blob/main/cmd/games/main.go"
click node_wallet_service "https://github.com/nutcas3/lets-bet/blob/main/cmd/wallet/main.go"
click node_settlement_service "https://github.com/nutcas3/lets-bet/blob/main/cmd/settlement/main.go"
click node_sports_http "https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/http/engine_handlers.go"
click node_bet_placement "https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/place_bet.go"
click node_odds_engine "https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/odds/engine.go"
click node_sports_live "https://github.com/nutcas3/lets-bet/blob/main/internal/sports/live/service.go"
click node_crash_engine "https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/games/crash_engine.go"
click node_fairness "https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/provably_fair.go"
click node_wallet_logic "https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/wallet/wallet.go"
click node_tax "https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/tax/tax.go"
click node_payments "https://github.com/nutcas3/lets-bet/blob/main/internal/tenant/ke/mpesa.go"
click node_compliance "https://github.com/nutcas3/lets-bet/blob/main/internal/compliance/bclb/service.go"
click node_kyc "https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/kyc/smileid.go"
click node_postgres "https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/repository/postgres/sport_bet_repository.go"
click node_redis "https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/storage/odds_cache.go"
click node_event_bus "https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/events/bus.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_engine,node_games_service,node_wallet_service,node_settlement_service toneBlue
class node_sports_http,node_bet_placement,node_odds_engine,node_sports_live,node_crash_engine,node_fairness toneAmber
class node_wallet_logic,node_tax,node_payments,node_compliance,node_kyc toneMint
class node_postgres,node_redis,node_event_bus toneRose
class node_bettor,node_odds_provider,node_payment_networks,node_identity_provider toneIndigo
```

## Components

### Service entry points

- [API gateway](https://github.com/nutcas3/lets-bet/blob/main/cmd/gateway/main.go): `cmd/gateway/main.go`
- [Betting engine](https://github.com/nutcas3/lets-bet/blob/main/cmd/engine/main.go): `cmd/engine/main.go`
- [Games service](https://github.com/nutcas3/lets-bet/blob/main/cmd/games/main.go): `cmd/games/main.go`
- [Wallet service](https://github.com/nutcas3/lets-bet/blob/main/cmd/wallet/main.go): `cmd/wallet/main.go`
- [Settlement service](https://github.com/nutcas3/lets-bet/blob/main/cmd/settlement/main.go): `cmd/settlement/main.go`

### Betting and games

- [Sports HTTP](https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/http/engine_handlers.go): `internal/infrastructure/http/engine_handlers.go`
- [Bet placement](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/place_bet.go): `internal/core/usecase/place_bet.go`
- [Odds engine](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/odds/engine.go): `internal/core/usecase/odds/engine.go`
- [Live sports](https://github.com/nutcas3/lets-bet/blob/main/internal/sports/live/service.go): `internal/sports/live/service.go`
- [Crash game engine](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/games/crash_engine.go): `internal/core/usecase/games/crash_engine.go`
- [Provably fair](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/provably_fair.go): `internal/core/usecase/provably_fair.go`

### Wallet and compliance

- [Wallet operations](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/wallet/wallet.go): `internal/core/usecase/wallet/wallet.go`
- [Tax calculations](https://github.com/nutcas3/lets-bet/blob/main/internal/core/usecase/tax/tax.go): `internal/core/usecase/tax/tax.go`
- [Country payment adapters](https://github.com/nutcas3/lets-bet/blob/main/internal/tenant/ke/mpesa.go): `internal/tenant/ke/mpesa.go`
- [BCLB compliance](https://github.com/nutcas3/lets-bet/blob/main/internal/compliance/bclb/service.go): `internal/compliance/bclb/service.go`
- [Smile ID KYC](https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/kyc/smileid.go): `internal/infrastructure/kyc/smileid.go`

### Shared infrastructure

- [PostgreSQL](https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/repository/postgres/sport_bet_repository.go): `internal/infrastructure/repository/postgres/sport_bet_repository.go`
- [Redis cache](https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/storage/odds_cache.go): `internal/infrastructure/storage/odds_cache.go`
- [NATS event bus](https://github.com/nutcas3/lets-bet/blob/main/internal/infrastructure/events/bus.go): `internal/infrastructure/events/bus.go`

### Other components

- **Bettor**
- **Sports odds feeds**
- **Payment networks**
- **Identity provider**

## Connections

- Bettor → API gateway: submits requests
- Bettor → Games service: plays crash game
- API gateway → Betting engine: routes betting
- API gateway → Wallet service: routes wallet
- API gateway → Games service: routes game
- Betting engine → Sports HTTP: registers routes
- Sports HTTP → Odds engine: handles odds
- Bet placement → Tax calculations: applies tax
- Bet placement → Wallet operations: reserves funds
- Bet placement → PostgreSQL: persists bet
- Odds engine → Sports odds feeds: fetches odds
- Odds engine → Redis cache: caches odds
- Odds engine → NATS event bus: publishes updates
- Odds engine → Redis cache: reads odds
- Live sports → Sports odds feeds: retrieves events
- Games service → Crash game engine: starts engine
- Crash game engine → Provably fair: generates outcomes
- Crash game engine → Wallet operations: uses wallet
- Crash game engine → Tax calculations: uses tax
- Crash game engine → PostgreSQL: stores game data
- Wallet service → Country payment adapters: initiates payment
- Country payment adapters → Payment networks: requests transfer
- Payment networks → Country payment adapters: sends callback
- Country payment adapters → Wallet operations: credits wallet
- BCLB compliance → Smile ID KYC: requests verification
- Smile ID KYC → Identity provider: verifies identity
- Settlement service → PostgreSQL: reads bet records
- Settlement service → Wallet operations: pays winners