Skip to main content

Architecture

Alpaca Universe is a Next.js application containing a Phaser game, connected to a Rust modular backend with MongoDB as the main database. The token and staking program run on Solana.

System overview​

                         ┌────────────────────────────┐
                         │       Solana Network       │
                         │                            │
                         │ ALPUN token mint            │
                         │ Staking program            │
                         │ Reward vault PDA           │
                         │ Player staking accounts    │
                         │ MPL Core NFT collection    │
                         └──────────────┬─────────────┘
                                        │ RPC / WebSocket
                                        │
┌──────────────────────────────┐        │        ┌─────────────────────────────┐
│         Next.js Web          │        │        │        Rust Backend         │
│                              │◄──HTTPS┼───────►│                             │
│ Marketing homepage           │        │        │ Axum REST API               │
│ Keycloak login (OIDC)        │        │        │ WebSocket game gateway      │
│ Wallet linking               │        │        │ Keycloak JWT validation     │
│ Staking dashboard            │        │        │ Wallet-link verification    │
│ Phaser game                  │        │        │ Game engine                 │
│ Inventory and leaderboard    │        │        │ Reward calculations         │
└──────────────────────────────┘        │        │ Solana indexer              │
               ▲                        │        │ Background workers          │
               │ OIDC                   │        └──────────────┬──────────────┘
      ┌────────┴─────────┐              │                       │
      │     Keycloak     │              │                       │
      │ (identity.       │              │                       │
      │  bitview.club,   │              │                       │
      │  realm "alpun")  │              │                       │
      └──────────────────┘              │                       │
                                        │                       │
                                        │                ┌──────▼──────┐
                                        │                │   MongoDB   │
                                        │                │             │
                                        │                │ Players     │
                                        │                │ Sessions    │
                                        │                │ Game state  │
                                        │                │ Missions    │
                                        │                │ Inventory   │
                                        │                │ Ledger      │
                                        │                └─────────────┘

Identity is provided by Keycloak — the cluster's existing instance at identity.bitview.club with a dedicated alpun realm. Players log in via OIDC (Authorization Code + PKCE); a Solana wallet is linked to the account afterwards and only needed for staking and NFT ownership. The backend validates Keycloak RS256 access tokens against cached JWKS.

The backend runs as three deployables sharing one Cargo workspace and the same domain crates:

alpun-api      Axum REST API + WebSocket gateway
alpun-worker   Timers: mission completion, energy, leaderboards, outbox
alpun-indexer  Watches Solana for staking events, updates projections

On-chain versus off-chain state​

Keep on-chain​

  • ALPUN token mint and ownership
  • Staking deposits, withdrawals, lock periods
  • Reward vault and token reward claims
  • Reward NFT ownership (MPL Core collection)

Keep in MongoDB​

  • Player experience, level and energy
  • Ordinary items, wool and farm resources
  • Missions, farm layout, achievements
  • Cosmetic selections, leaderboard points
  • Anti-cheat records

Never trust from the frontend​

  • Player token balance
  • Amount staked
  • Mission reward or completion time
  • Random reward result
  • Energy balance, item quantity, leaderboard score

The client can display animations immediately, but the backend must decide whether the player actually receives a reward.

Final asset model​

ALPUN
├── On-chain SPL token
├── Tradable on a DEX
├── Used for premium actions
├── Optional payments or burns
└── Used for special events

GRASS, WATER, WOOL, WOOD, STONE, ...
├── Stored in MongoDB
├── Managed by the Rust backend
├── Used for crafting and construction
└── Not transferable outside the game

NFTs
├── On-chain (MPL Core)
├── Visible in the player's wallet
├── Won through gameplay and events
└── Usable inside Alpaca Universe

Staking-to-game loop​

Stake ALPUN on-chain
  → indexer observes the position
  → daily Alpaca Energy allowance grows
  → energy is spent on farm actions
  → actions earn resources and seasonal points
  → Season 0: NFT rewards only (zero token emissions)

See Staking for the exact formula and lock tiers.

Deployment stack​

Kubernetes
├── alpun-web deployment          (Next.js, 2 replicas)
├── alpun-api deployment          (Rust API, 2 replicas)
├── alpun-worker deployment       (1–2 replicas)
├── alpun-indexer deployment      (1 active replica)
├── MongoDB replica set           (persistent storage)
├── optional Redis                (cross-replica WebSocket rooms, later)
├── ingress-nginx + cert-manager
└── Prometheus / Grafana / Loki

Deploys are GitOps-driven: app repos build images in CI and bump the tag in alpun-gitops; ArgoCD reconciles the cluster. See Operations → Deployment.

The one-line rule​

Phaser controls the presentation, Rust controls the game rules, MongoDB controls off-chain persistence, and Solana controls financial ownership.