# Project Progress

Ludo King tournament platform (Bangladesh): players pay an entry fee, play 1v1 in Ludo King, and the
winner gets 90% of the pool. Roadmap: `Ludo_Platform_FullStack_DualDev_Roadmap.pdf`.

**Last updated:** 2026-09-10 · Update this file in the same commit as your work.

## Status

| Phase | What                                   | Developer 1 | Developer 2 |
| ----- | -------------------------------------- | ----------- | ----------- |
| 1     | Setup & login                          | ✅ Done     | ✅ Done (by Dev 1) |
| 2     | Wallet, payments & match lobby         | ✅ Done     | ✅ Done (by Dev 1) |
| 3     | Live updates, TRThunder room, results  | ⬜ Next     | ⬜ Next     |
| 4     | Admin panel, notifications, APK        | ⬜          | ⬜          |

Milestones 1 and 2 are verified by automated browser tests.

## What works today

- **Accounts:** register, log in, log out, reset password with an SMS code, edit profile.
- **Wallet:** deposit via bKash/Nagad/Rocket (user sends money, enters the TrxID, an admin approves),
  withdraw (money is held until an admin pays it out, user can cancel), full transaction history.
- **Matches:** lobby with ৳50/100/200/500 matches, open a match or take the free seat ("সিট পূরণ"),
  the entry fee is locked when you join, match page, "my matches" history.
- **App:** Bengali landing page, phone-first layout with bottom tabs (খেলুন · আমার ম্যাচ · ওয়ালেট · প্রোফাইল).

## How to run

```bash
cd backend  && pnpm install && pnpm dev   # API on http://localhost:4000 (copy .env.example to .env first)
cd frontend && pnpm install && pnpm dev   # app on http://localhost:3000
```

- `pnpm test` (backend): 27 tests against the database, including money and race-condition cases.
- `pnpm test:e2e` (frontend): 4 browser tests (login, password reset, wallet, match join).
- `pnpm grant-admin <phone>` (backend): make a user an admin (they log in again).
- SMS codes are printed in the backend log for now (no real SMS provider yet).

## For Developer 2: how the code is laid out

- **Backend** `backend/src/modules/<feature>/`: `routes → controller → service`, plus `validation`
  (Zod) and `dto` (what the API returns). Modules: `auth`, `users`, `wallet`, `matches`.
- **Frontend** `frontend/src/features/<feature>/`: `api`, `hooks` (TanStack Query), `components`,
  `copy.ts` (all Bengali text). Pages in `frontend/src/app/` just render a feature screen.
- **Database:** Prisma (`backend/prisma/schema.prisma`) on Neon. After a schema change:
  `pnpm db:migrate`, then `pnpm db:generate`.

**Rules that matter:**

1. **Money is stored in paisa** (integers, ৳1 = 100). The API sends taka. Never use floats for money.
2. **Never change balances directly.** Use the escrow functions in
   `backend/src/modules/wallet/escrow.service.ts`:
   - `lockFunds`: hold an entry fee (used when joining a match)
   - `refundEntry` / `refundMatchEntries`: give fees back (cancelled match)
   - `releaseWinnerPayout`: pay the winner 90%, record the 10% commission
3. Every API error has a stable `code`; add its Bengali text in `frontend/src/lib/api/error-messages.ts`.

**Where Phase 3 plugs in:**

- When a match fills, `joinMatch` in `backend/src/modules/matches/matches.service.ts` marks it `FULL`.
  That is the place to create the TRThunder room and save the code in the `match_rooms` table.
- The match page already shows the room code when it exists (`roomCode` in the API response).
- The lobby and match page refresh every 5 seconds; Socket.io should replace that.
- For results, call `releaseWinnerPayout({ matchId, winnerUserId })` and set the match to `COMPLETED`.

## Known issues

- **A full match can't finish yet:** there is no room code or result until Phase 3, and no admin
  cancel. Until then, both players' fees stay locked and they can't join another match.
- Deposit numbers in `backend/.env` are placeholders; real bKash/Nagad/Rocket numbers are needed.
- No real SMS provider yet; no admin screen yet (Phase 4); not yet tested on a real Android phone.
- Test runs leave test users in the dev database.

## Changelog

| Date       | Change |
| ---------- | ------ |
| 2026-09-10 | Phase 1: project setup, login/registration, profile, app shell, landing page |
| 2026-09-10 | Switched the database to Neon |
| 2026-09-10 | Phase 2: wallet (deposits, withdrawals, escrow) and match lobby (open, join, cancel) |
| 2026-09-10 | Fixed the Bengali digit "১" rendering (digits now use Noto Sans Bengali); simplified this file |