# monaliens/monaliens-platform architecture

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

- Interactive diagram: https://gitdiagram.com/monaliens/monaliens-platform
- Repository: https://github.com/monaliens/monaliens-platform

## Overview

Monaliens is an on-chain gaming and social platform. The main player workflow is: use the React frontend to play a game, send HTTP/WebSocket traffic through the central Express API to a game backend, and settle verifiable outcomes through blockchain contracts using Pyth Entropy. The repository also contains NFT and social services, trading and raffle products, staking and auction contracts, and supporting tools. The README documents the high-level topology; sampled source confirms several individual service responsibilities, but not every runtime connection.

Main entry points: [`games`](https://github.com/monaliens/monaliens-platform/tree/main/games) (Game backends), [`api/src/index.js`](https://github.com/monaliens/monaliens-platform/blob/main/api/src/index.js) (Central API), [`contracts/auction/backend/src/server.js`](https://github.com/monaliens/monaliens-platform/blob/main/contracts/auction/backend/src/server.js) (Auction backend), [`frontend/src/App.js`](https://github.com/monaliens/monaliens-platform/blob/main/frontend/src/App.js) (React frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player experience"]
  node_frontend["React frontend<br/>[App.js]"]
end

subgraph group_gaming["On-chain gaming"]
  node_game_backends["Game backends"]
  node_blackjack["Blackjack runtime<br/>[gameHandler.js]"]
  node_hilo["Hi-Lo runtime<br/>[server.js]"]
  node_mines["Mines runtime<br/>[server.js]"]
end

subgraph group_platform["Platform services"]
  node_central_api["Central API<br/>[index.js]"]
  node_nft_metadata["NFT metadata<br/>[nft.routes.js]"]
  node_redis[("Redis services<br/>[redisService.js]")]
  node_game_wallet["Game wallet"]
  node_tournaments["Tournament tracking"]
  node_discord["Discord tooling<br/>[database.ts]"]
end

subgraph group_marketplace["Marketplace products"]
  node_auction_backend["Auction backend<br/>[server.js]"]
  node_auction_services["Auction services<br/>[eventListener.js]"]
  node_raffle["Raffle platform<br/>[server.js]"]
  node_p2p["P2P trading<br/>[server.ts]"]
  node_airdrop["Staker airdrop<br/>[airdrop.js]"]
  node_tee_wallet["TEE game wallet<br/>[teeClient.js]"]
  node_allowlist["Whitelist checker<br/>[App.jsx]"]
end

subgraph group_chain["Contracts and indexing"]
  node_blockchain[("Monad blockchain")]
  node_pyth["Pyth Entropy"]
  node_staking["Staking contracts"]
  node_event_indexer["Event listener<br/>[ContractHandler.js]"]
end

node_players(("Players"))

node_players -->|"use"| node_frontend
node_frontend -->|"HTTP and WebSocket"| node_central_api
node_central_api -->|"proxy traffic"| node_game_backends
node_game_backends -->|"settle games"| node_blockchain
node_game_backends -->|"request randomness"| node_pyth
node_central_api -->|"routes requests"| node_nft_metadata
node_nft_metadata -->|"uses cache"| node_redis
node_central_api -.->|"uses services"| node_redis
node_central_api -.->|"tracks tournaments"| node_tournaments
node_central_api -.->|"maps wallets"| node_game_wallet
node_game_backends -->|"includes"| node_blackjack
node_game_backends -->|"includes"| node_hilo
node_game_backends -->|"includes"| node_mines
node_auction_backend -->|"starts listener"| node_auction_services
node_auction_backend -.->|"syncs contracts"| node_blockchain
node_raffle -->|"runs on-chain raffles"| node_blockchain
node_p2p -->|"trades on-chain assets"| node_blockchain
node_airdrop -->|"airdrops to stakers"| node_staking
node_tee_wallet -->|"supports game UX"| node_game_backends
node_event_indexer -->|"indexes events"| node_blockchain
node_allowlist -->|"verifies Merkle proofs"| node_blockchain
node_discord -.->|"integrates Discord"| node_central_api

click node_frontend "https://github.com/monaliens/monaliens-platform/blob/main/frontend/src/App.js"
click node_central_api "https://github.com/monaliens/monaliens-platform/blob/main/api/src/index.js"
click node_nft_metadata "https://github.com/monaliens/monaliens-platform/blob/main/api/src/routes/nft.routes.js"
click node_redis "https://github.com/monaliens/monaliens-platform/blob/main/api/src/services/redisService.js"
click node_game_wallet "https://github.com/monaliens/monaliens-platform/blob/main/api/src/services/gameWalletMappingService.js"
click node_tournaments "https://github.com/monaliens/monaliens-platform/blob/main/api/src/services/tournamentService.js"
click node_game_backends "https://github.com/monaliens/monaliens-platform/tree/main/games"
click node_blackjack "https://github.com/monaliens/monaliens-platform/blob/main/games/blackjack/backend/gameHandler.js"
click node_hilo "https://github.com/monaliens/monaliens-platform/blob/main/games/hilo/backend/server.js"
click node_mines "https://github.com/monaliens/monaliens-platform/blob/main/games/mines/backend/server.js"
click node_staking "https://github.com/monaliens/monaliens-platform/tree/main/contracts/staking"
click node_auction_backend "https://github.com/monaliens/monaliens-platform/blob/main/contracts/auction/backend/src/server.js"
click node_auction_services "https://github.com/monaliens/monaliens-platform/blob/main/contracts/auction/backend/src/services/eventListener.js"
click node_raffle "https://github.com/monaliens/monaliens-platform/blob/main/tools/raffle/backend/src/server.js"
click node_p2p "https://github.com/monaliens/monaliens-platform/blob/main/tools/p2p/backend/src/server.ts"
click node_airdrop "https://github.com/monaliens/monaliens-platform/blob/main/tools/airdrop/airdrop.js"
click node_tee_wallet "https://github.com/monaliens/monaliens-platform/blob/main/tools/tee-wallet/api/src/teeClient.js"
click node_event_indexer "https://github.com/monaliens/monaliens-platform/blob/main/tools/event-listener/src/core/ContractHandler.js"
click node_allowlist "https://github.com/monaliens/monaliens-platform/blob/main/tools/whitelist-checker/frontend/src/App.jsx"
click node_discord "https://github.com/monaliens/monaliens-platform/blob/main/tools/dc-bot/src/services/database.ts"

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_frontend toneBlue
class node_game_backends,node_blackjack,node_hilo,node_mines toneAmber
class node_central_api,node_nft_metadata,node_redis,node_game_wallet,node_tournaments,node_discord toneMint
class node_auction_backend,node_auction_services,node_raffle,node_p2p,node_airdrop,node_tee_wallet,node_allowlist toneRose
class node_blockchain,node_pyth,node_staking,node_event_indexer,node_players toneIndigo
```

## Components

### Player experience

- [React frontend](https://github.com/monaliens/monaliens-platform/blob/main/frontend/src/App.js): `frontend/src/App.js`

### On-chain gaming

- [Game backends](https://github.com/monaliens/monaliens-platform/tree/main/games): `games`
- [Blackjack runtime](https://github.com/monaliens/monaliens-platform/blob/main/games/blackjack/backend/gameHandler.js): `games/blackjack/backend/gameHandler.js`
- [Hi-Lo runtime](https://github.com/monaliens/monaliens-platform/blob/main/games/hilo/backend/server.js): `games/hilo/backend/server.js`
- [Mines runtime](https://github.com/monaliens/monaliens-platform/blob/main/games/mines/backend/server.js): `games/mines/backend/server.js`

### Platform services

- [Central API](https://github.com/monaliens/monaliens-platform/blob/main/api/src/index.js): `api/src/index.js`
- [NFT metadata](https://github.com/monaliens/monaliens-platform/blob/main/api/src/routes/nft.routes.js): `api/src/routes/nft.routes.js`
- [Redis services](https://github.com/monaliens/monaliens-platform/blob/main/api/src/services/redisService.js): `api/src/services/redisService.js`
- [Game wallet](https://github.com/monaliens/monaliens-platform/blob/main/api/src/services/gameWalletMappingService.js): `api/src/services/gameWalletMappingService.js`
- [Tournament tracking](https://github.com/monaliens/monaliens-platform/blob/main/api/src/services/tournamentService.js): `api/src/services/tournamentService.js`
- [Discord tooling](https://github.com/monaliens/monaliens-platform/blob/main/tools/dc-bot/src/services/database.ts): `tools/dc-bot/src/services/database.ts`

### Marketplace products

- [Auction backend](https://github.com/monaliens/monaliens-platform/blob/main/contracts/auction/backend/src/server.js): `contracts/auction/backend/src/server.js`
- [Auction services](https://github.com/monaliens/monaliens-platform/blob/main/contracts/auction/backend/src/services/eventListener.js): `contracts/auction/backend/src/services/eventListener.js`
- [Raffle platform](https://github.com/monaliens/monaliens-platform/blob/main/tools/raffle/backend/src/server.js): `tools/raffle/backend/src/server.js`
- [P2P trading](https://github.com/monaliens/monaliens-platform/blob/main/tools/p2p/backend/src/server.ts): `tools/p2p/backend/src/server.ts`
- [Staker airdrop](https://github.com/monaliens/monaliens-platform/blob/main/tools/airdrop/airdrop.js): `tools/airdrop/airdrop.js`
- [TEE game wallet](https://github.com/monaliens/monaliens-platform/blob/main/tools/tee-wallet/api/src/teeClient.js): `tools/tee-wallet/api/src/teeClient.js`
- [Whitelist checker](https://github.com/monaliens/monaliens-platform/blob/main/tools/whitelist-checker/frontend/src/App.jsx): `tools/whitelist-checker/frontend/src/App.jsx`

### Contracts and indexing

- **Monad blockchain**
- **Pyth Entropy**
- [Staking contracts](https://github.com/monaliens/monaliens-platform/tree/main/contracts/staking): `contracts/staking`
- [Event listener](https://github.com/monaliens/monaliens-platform/blob/main/tools/event-listener/src/core/ContractHandler.js): `tools/event-listener/src/core/ContractHandler.js`

### Other components

- **Players**

## Connections

- Players → React frontend: use (evidence: `README.md`)
- React frontend → Central API: HTTP and WebSocket (evidence: `README.md`)
- Central API → Game backends: proxy traffic (evidence: `README.md`)
- Game backends → Monad blockchain: settle games (evidence: `README.md`)
- Game backends → Pyth Entropy: request randomness (evidence: `README.md`)
- Central API → NFT metadata: routes requests
- NFT metadata → Redis services: uses cache
- Central API → Redis services: uses services
- Central API → Tournament tracking: tracks tournaments
- Central API → Game wallet: maps wallets
- Game backends → Blackjack runtime: includes (evidence: `README.md`)
- Game backends → Hi-Lo runtime: includes (evidence: `README.md`)
- Game backends → Mines runtime: includes (evidence: `README.md`)
- Auction backend → Auction services: starts listener (evidence: `contracts/auction/backend/src/server.js`)
- Auction backend → Monad blockchain: syncs contracts
- Raffle platform → Monad blockchain: runs on-chain raffles (evidence: `README.md`)
- P2P trading → Monad blockchain: trades on-chain assets (evidence: `README.md`)
- Staker airdrop → Staking contracts: airdrops to stakers (evidence: `README.md`)
- TEE game wallet → Game backends: supports game UX (evidence: `README.md`)
- Event listener → Monad blockchain: indexes events (evidence: `README.md`)
- Whitelist checker → Monad blockchain: verifies Merkle proofs (evidence: `README.md`)
- Discord tooling → Central API: integrates Discord