# taimoor822/dicemajlis architecture

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

- Interactive diagram: https://gitdiagram.com/taimoor822/dicemajlis
- Repository: https://github.com/taimoor822/dicemajlis

## Overview

Dice Majlis is a multiplayer Ludo platform: players use the Flutter app to sign in, manage a profile and currency, join private rooms, and play server-controlled games. The backend owns room actions, game state, turn timing, and move history; a registry selects the game implementation, with a pure Ludo engine enforcing rules. Daily rewards grant currency through the wallet ledger. The README documents app capabilities, but Flutter application source files were not present in the supplied tree, so the client is represented by its enclosing directory; some backend routes and real-time wiring are likewise unsampled.

Main entry points: [`frontend/dice_majlis_app`](https://github.com/taimoor822/dicemajlis/tree/main/frontend/dice_majlis_app) (Flutter client), [`backend/core/game/services.py`](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/services.py) (Game service), [`backend/core/ludo_engine/engine.py`](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/engine.py) (Ludo rules engine), [`backend/core/rewards/engine.py`](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/engine.py) (Reward engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Player app"]
  node_flutter["Flutter client"]
end

subgraph group_identity["Identity and profile"]
  node_accounts["Accounts"]
  node_account_data[("Account records<br/>[models.py]")]
  node_profiles["Profiles<br/>[services.py]"]
  node_profile_data[("Profile records<br/>[models.py]")]
end

subgraph group_economy["Wallet and rewards"]
  node_wallet["Wallet ledger<br/>[services.py]"]
  node_wallet_data[("Wallet records<br/>[models.py]")]
  node_daily_rewards["Daily rewards<br/>[daily.py]"]
  node_reward_engine["Reward engine<br/>[engine.py]"]
  node_reward_data[("Reward claims<br/>[models.py]")]
end

subgraph group_play["Game platform"]
  node_room_api["Room API<br/>[views.py]"]
  node_live_game["Game service<br/>[services.py]"]
  node_room_data[("Rooms and games<br/>[models.py]")]
  node_realtime["WebSocket play<br/>[consumers.py]"]
  node_turn_timer["Turn timer<br/>[timers.py]"]
  node_registry["Game registry<br/>[registry.py]"]
  node_ludo_adapter["Ludo adapter<br/>[ludo.py]"]
  node_ludo_table["Ludo table data<br/>[ludo.py]"]
  node_ludo_engine["Ludo rules engine<br/>[engine.py]"]
  node_game_state["Game state<br/>[state.py]"]
  node_board_rules["Board geometry<br/>[board.py]"]
  node_bot["Bot moves<br/>[bot.py]"]
end

node_player(("Player"))

node_player -->|"plays through"| node_flutter
node_flutter -->|"signs in"| node_accounts
node_accounts -.->|"manages accounts"| node_account_data
node_flutter -->|"views profile"| node_profiles
node_profiles -->|"reads and updates"| node_profile_data
node_flutter -->|"checks balances"| node_wallet
node_flutter -->|"claims reward"| node_daily_rewards
node_daily_rewards -.->|"grants bundle"| node_reward_engine
node_reward_engine -->|"records claim"| node_reward_data
node_reward_engine -->|"posts currency"| node_wallet
node_wallet -->|"writes ledger"| node_wallet_data
node_flutter -->|"creates or joins"| node_room_api
node_room_api -.->|"dispatches actions"| node_live_game
node_realtime -.->|"submits actions"| node_live_game
node_turn_timer -.->|"fires timeout"| node_live_game
node_live_game -->|"persists game"| node_room_data
node_live_game -->|"selects game"| node_registry
node_registry -.->|"registers game"| node_ludo_adapter
node_live_game -->|"uses table extras"| node_ludo_table
node_ludo_adapter -.->|"delegates rules"| node_ludo_engine
node_ludo_engine -->|"transitions state"| node_game_state
node_ludo_engine -->|"checks geometry"| node_board_rules
node_bot -->|"chooses moves"| node_ludo_engine

click node_flutter "https://github.com/taimoor822/dicemajlis/tree/main/frontend/dice_majlis_app"
click node_accounts "https://github.com/taimoor822/dicemajlis/tree/main/backend/core/accounts"
click node_account_data "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/accounts/models.py"
click node_profiles "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/profiles/services.py"
click node_profile_data "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/profiles/models.py"
click node_wallet "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/wallet/services.py"
click node_wallet_data "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/wallet/models.py"
click node_daily_rewards "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/daily.py"
click node_reward_engine "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/engine.py"
click node_reward_data "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/models.py"
click node_room_api "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/views.py"
click node_live_game "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/services.py"
click node_room_data "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/models.py"
click node_realtime "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/consumers.py"
click node_turn_timer "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/timers.py"
click node_registry "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game_platform/registry.py"
click node_ludo_adapter "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game_platform/ludo.py"
click node_ludo_table "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/tables/ludo.py"
click node_ludo_engine "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/engine.py"
click node_game_state "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/state.py"
click node_board_rules "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/board.py"
click node_bot "https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/bot.py"

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_flutter toneBlue
class node_accounts,node_account_data,node_profiles,node_profile_data toneAmber
class node_wallet,node_wallet_data,node_daily_rewards,node_reward_engine,node_reward_data toneMint
class node_room_api,node_live_game,node_room_data,node_realtime,node_turn_timer,node_registry,node_ludo_adapter,node_ludo_table,node_ludo_engine,node_game_state,node_board_rules,node_bot toneRose
class node_player toneIndigo
```

## Components

### Player app

- [Flutter client](https://github.com/taimoor822/dicemajlis/tree/main/frontend/dice_majlis_app): `frontend/dice_majlis_app`

### Identity and profile

- [Accounts](https://github.com/taimoor822/dicemajlis/tree/main/backend/core/accounts): `backend/core/accounts`
- [Account records](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/accounts/models.py): `backend/core/accounts/models.py`
- [Profiles](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/profiles/services.py): `backend/core/profiles/services.py`
- [Profile records](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/profiles/models.py): `backend/core/profiles/models.py`

### Wallet and rewards

- [Wallet ledger](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/wallet/services.py): `backend/core/wallet/services.py`
- [Wallet records](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/wallet/models.py): `backend/core/wallet/models.py`
- [Daily rewards](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/daily.py): `backend/core/rewards/daily.py`
- [Reward engine](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/engine.py): `backend/core/rewards/engine.py`
- [Reward claims](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/rewards/models.py): `backend/core/rewards/models.py`

### Game platform

- [Room API](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/views.py): `backend/core/game/views.py`
- [Game service](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/services.py): `backend/core/game/services.py`
- [Rooms and games](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/models.py): `backend/core/game/models.py`
- [WebSocket play](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/consumers.py): `backend/core/game/consumers.py`
- [Turn timer](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/timers.py): `backend/core/game/timers.py`
- [Game registry](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game_platform/registry.py): `backend/core/game_platform/registry.py`
- [Ludo adapter](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game_platform/ludo.py): `backend/core/game_platform/ludo.py`
- [Ludo table data](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/game/tables/ludo.py): `backend/core/game/tables/ludo.py`
- [Ludo rules engine](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/engine.py): `backend/core/ludo_engine/engine.py`
- [Game state](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/state.py): `backend/core/ludo_engine/state.py`
- [Board geometry](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/board.py): `backend/core/ludo_engine/board.py`
- [Bot moves](https://github.com/taimoor822/dicemajlis/blob/main/backend/core/ludo_engine/bot.py): `backend/core/ludo_engine/bot.py`

### Other components

- **Player**

## Connections

- Player → Flutter client: plays through (evidence: `README.md`)
- Flutter client → Accounts: signs in (evidence: `README.md`)
- Accounts → Account records: manages accounts (evidence: `backend/core/accounts/authentication.py`)
- Flutter client → Profiles: views profile (evidence: `README.md`)
- Profiles → Profile records: reads and updates (evidence: `backend/core/profiles/services.py`)
- Flutter client → Wallet ledger: checks balances (evidence: `README.md`)
- Flutter client → Daily rewards: claims reward (evidence: `README.md`)
- Daily rewards → Reward engine: grants bundle
- Reward engine → Reward claims: records claim (evidence: `backend/core/rewards/engine.py`)
- Reward engine → Wallet ledger: posts currency (evidence: `backend/core/rewards/engine.py`)
- Wallet ledger → Wallet records: writes ledger (evidence: `backend/core/wallet/services.py`)
- Flutter client → Room API: creates or joins (evidence: `README.md`)
- Room API → Game service: dispatches actions
- WebSocket play → Game service: submits actions
- Turn timer → Game service: fires timeout
- Game service → Rooms and games: persists game (evidence: `backend/core/game/services.py`)
- Game service → Game registry: selects game (evidence: `backend/core/game/services.py`)
- Game registry → Ludo adapter: registers game
- Game service → Ludo table data: uses table extras (evidence: `backend/core/game/services.py`)
- Ludo adapter → Ludo rules engine: delegates rules
- Ludo rules engine → Game state: transitions state (evidence: `backend/core/ludo_engine/engine.py`)
- Ludo rules engine → Board geometry: checks geometry (evidence: `backend/core/ludo_engine/engine.py`)
- Bot moves → Ludo rules engine: chooses moves (evidence: `backend/core/ludo_engine/bot.py`)
