Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Windows
Saved setup from 16 h ago
Will it work on Windows?
Heads-upBuilding it yourself? It also needs 86 settings in .env (11 secret).
DEVELOPMENT.mdLast updated: 2026-11-19 (Single Player: Round Bank with you + 3 bots, rotating banker, banker advantage)
This repository contains the Laravel web application + shared backend (repo root) and the
Next.js + Capacitor mobile application (mobile/). Laravel is the single source of truth for
game rules, scoring, wallets, commissions and permissions. Both frontends only call /api/v1 and
listen to Laravel Reverb.
Inspected https://gitlab.com/czar.gaba/baseplate-react (commit 60eefa0) before building:
| Item | Finding |
| --- | --- |
| What it is | Already a Laravel 13 application, not a standalone React SPA |
| Frontend | React 19 (.jsx), Inertia.js v3 (@inertiajs/react), Vite 7 |
| Routing | Laravel routes → Inertia::render('Page') → resources/js/Pages/*.jsx |
| CSS | Tailwind CSS v4 via @tailwindcss/vite, TailAdmin design tokens in resources/css/style.css (brand #465FFF, Outfit font, dark mode via .dark) |
| Layout | AuthenticatedLayout (Sidebar + Header + Overlay + Preloader), GuestLayout |
| Components | Sidebar, Header, Breadcrumb, FlashMessage, MetricGroup, ApexChart, WorldMap, RecentOrdersTable, UserForm, Icons |
| Extras installed | ApexCharts, FullCalendar, jsvectormap, flatpickr, dropzone, Alpine |
| Tests | Pest 4 (tests/Feature/AuthAndCrudTest.php) |
| Auth | Session login by username, CRUD users demo at /crud |
Integration strategy: Baseplate is the Laravel web app, so it was adopted as the project root (no porting). Everything was built on top of it:
resources/js/Components/ui.tsx,
DataTable.tsx, PageShell.tsx) that reuses Baseplate's exact class names.tsconfig.json, allowJs); new pages are
.tsx, Baseplate pages stay .jsx. The page resolver loads either, code-split.resources/js/lib/navigation.ts).resources/js/Pages/Baseplate/Dashboard.jsx
(unrouted). Baseplate's /crud user screens are kept but restricted to Super Admin (they were
open to every logged-in user, which would let players edit accounts).Header.jsx used IconUsers without importing it (profile dropdown crash).AGENTS.md (Laravel Boost guidelines) was not copied because Windows
filenames are case-insensitive and it would overwrite this project's agents.md.public/images/logo/pusoy-*.svg, public/favicon.svg).Web ↔ API: Web pages are thin Inertia shells; data and actions go through the same
/api/v1 endpoints as the mobile app, authenticated by the web session cookie (Sanctum
"stateful" mode). The mobile app uses Sanctum bearer tokens. No business logic exists in either
frontend (hand names/foul hints come from the server POST /games/{id}/preview endpoint).
Requirements: XAMPP (PHP 8.3+, MariaDB/MySQL), Composer, Node 20+. Database 553 must exist.
composer install
npm install
cp .env.example .env # then set DB_DATABASE=553 (already done in this checkout)
php artisan key:generate
php artisan migrate --seed # roles, permissions, rooms, local demo accounts
npm run build # or: npm run dev
Run these processes (separate terminals), or use composer dev for the first three:
php artisan serve # http://localhost:8000
php artisan queue:work --sleep=1 --tries=3 # broadcasts, timers, settlement jobs
php artisan reverb:start --host=0.0.0.0 --port=8080 # websockets
php artisan schedule:work # pusoy:sweep every minute
Local demo accounts (password password, created only when APP_ENV=local):
| Username | Role |
| --- | --- |
| superadmin | Super Admin |
| admin | Administrator (all abilities except audit logs) |
| agent, agent2 | Agents (agent owns player, demo1–demo6) |
| player, demo1…demo12 | Players (Chips from a fresh seed: 1,000 each; Gold from the Out of Gold claim) |
Testing a full game alone: join a room as player in the browser, then
php artisan pusoy:fill-table vc-starter seats and readies three demo players, and
php artisan pusoy:fill-table vc-starter --submit makes them submit (dev-only command).
cd mobile
cp .env.example .env.local # set NEXT_PUBLIC_REVERB_APP_KEY = backend REVERB_APP_KEY
npm install
npm run dev # http://localhost:3000 (browser preview)
npm run build && npx cap sync # static export to out/ and copy into android/ + ios/
npx cap open android # Android Studio (Windows/macOS/Linux)
npx cap open ios # Xcode (macOS only)
On a physical phone use your PC's LAN IP in NEXT_PUBLIC_API_URL/NEXT_PUBLIC_REVERB_HOST.
Icons/splash: edit mobile/assets/*.svg, re-render the PNGs, then npm run assets.
php artisan test --compact # 164 Pest tests (unit + feature), SQLite in-memory
vendor/bin/pest -c phpunit.mysql.xml # real-MySQL concurrency suite (parallel processes)
npm test # web Vitest + Testing Library
cd mobile && npm test # mobile Vitest + Testing Library
vendor/bin/pint --format agent # PHP formatting
npx tsc --noEmit && (cd mobile && npx tsc --noEmit)
Concurrency suite: tests/Concurrency launches several PHP processes at the same moment
(tests/Concurrency/worker.php) against the separate database 553_testing (create it once:
CREATE DATABASE \553_testing`; your dev database 553is never touched). It covers parallel debits (no overdraft), one idempotency key used concurrently, 8 simultaneous joins → exactly two full tables, duplicate joins by one player, and simultaneous final submissions/resolves → settled once. It found real races under MySQL's default REPEATABLE READ (stale snapshots after waiting on a lock); the fix isisolation_level = READ COMMITTEDinconfig/database.php(envDB_ISOLATION_LEVEL`)
plus locking reads where decisions are made. Keep it at READ COMMITTED.
# Android Studio's bundled JDK 25 needs Gradle 9.1+ (wrapper already bumped from 8.14.3)
export JAVA_HOME="/c/Program Files/Android/Android Studio/jbr"
cd mobile && npm run build && npx cap sync android
cd android && ./gradlew assembleDebug # → android/app/build/outputs/apk/debug/app-debug.apk
Testing on the Android emulator against your local backend (plain http):
NEXT_PUBLIC_API_URL=http://10.0.2.2:8000 NEXT_PUBLIC_REVERB_HOST=10.0.2.2 npm run build
CAP_DEV_HTTP=1 npx cap sync android # LOCAL ONLY: allows cleartext http; never ship it
Run a normal npm run build && npx cap sync afterwards so the native project goes back to https-only.
Backend: app/Notifications/Channels/PushChannel.php + app/Services/Push/FcmClient.php
(FCM HTTP v1, service-account JWT signed with OpenSSL; no extra packages). Set FCM_PROJECT_ID
and FCM_CREDENTIALS (absolute path to the service-account JSON, outside public/ and git).
Without them pushes are only logged. Pushes sent: room invitation, points received, cards dealt
(no card data). Dead tokens are cleared automatically.
Mobile: @capacitor/push-notifications registers the device token via
PUT /api/v1/auth/devices/push-token. Only set NEXT_PUBLIC_PUSH_ENABLED=true after adding
mobile/android/app/google-services.json (and enabling Push + uploading the APNs key in Firebase
for iOS). Registering without Firebase crashes the Android app; this was reproduced on the
emulator and is why the flag defaults to false.
| Area | Location |
| --- | --- |
| Game engine (pure PHP, no Laravel) | app/Game/ — Card, Deck, SeededRandom, HandEvaluator, HandValue, Arrangement, ArrangementValidator, Scorer, AutoArranger, Payout/* |
| Game state machine | app/Services/Game/GameEngine.php |
| Seating / ready / heartbeat / sweeps | app/Services/Game/TableService.php |
| Settlement | app/Services/Game/SettlementService.php |
| Per-viewer state (card visibility) | app/Services/Game/GameStatePresenter.php |
| Ledger (only code that changes balances) | app/Services/Wallet/LedgerService.php |
| Wallets, daily reward, reconciliation | app/Services/Wallet/WalletService.php |
| Allocation / adjustments / freezing | app/Services/Wallet/AllocationService.php |
| Commissions / cash payout requests (flagged) | app/Services/Agent/CommissionService.php, PayoutService.php |
| Users, hierarchy, referral codes | app/Services/Users/UserManagementService.php |
| API | routes/api.php, app/Http/Controllers/Api/V1/**, app/Http/Resources/*, app/Http/Requests/* |
| Web routes (Inertia) | routes/web.php |
| Broadcast channels | routes/channels.php; events app/Events/Game/* |
| Jobs / commands | app/Jobs/*, app/Console/Commands/*, schedule in routes/console.php |
| Config & feature flags | config/pusoy.php |
| Web pages | resources/js/Pages/{Player,Agent,Admin,Account,Auth} |
| Mobile app | mobile/src/app/* (screens), mobile/src/lib/* (API, auth, Echo) |
Hierarchy: Super Admin → Administrator → Agent → Player (users.role, App\Enums\Role).
php artisan pusoy:create-super-admin <username> <email>.permissions + permission_user,
App\Enums\Ability): manage_players, manage_agents, allocate_points, manage_rooms,
review_transactions, view_reports, manage_commissions, manage_games, view_audit_logs,
freeze_allocations; plus optional per-currency allocation limits (administrator_limits).agent_players.player_id is unique). They cannot create
agents/admins, touch other agents' players, change balances or rates, edit history or approve
their own commissions.Enforcement: Gates (one per ability + staff, super-admin, agent, play), Policies
(UserPolicy, GameSessionPolicy), role: middleware, service-level checks (defence in depth),
EnsureActiveAccount for suspended users. Every sensitive action writes audit_logs (append-only).
App\Enums\Currency), two independent wallet systems:
GD) — Single Player only: bets, winnings, losses and the free Out of Gold reward.CH) — Multiplayer only: rooms, lobbies, Round Bank / Banker Mode entry, bets, winnings,
losses, platform fees, agent allocations and commissions.
Neither is cash: there are no deposits, withdrawals, redemption or payouts, and the two can never be
mixed, transferred or exchanged (LedgerService refuses a transfer whose wallets are not all in the
transfer currency; every Multiplayer validator accepts only CH — Currency::multiplayer(); Single
Player only ever touches GD). Cash Points, Virtual Coins and Gold Points were removed on 2026-11-19
(migration 2026_11_19_180000_gold_and_chips_only, see §10)."2000.50"), converted by App\Support\Points. No floats touch balances.wallets table: (user, currency, type) where type ∈ player, allocation,
commission, plus system wallets escrow:{GD|CH} and platform:{GD|CH}. Players get a Gold and a Chips
player wallet; admins and agents also get Chips allocation / commission wallets (never Gold). The spec's
agent_wallets / agent_wallet_transactions are these allocation/commission wallets — there is
deliberately no second wallet system.wallet_transactions is immutable (model blocks update/delete): unique reference, idempotency key,
type, currency, source/destination wallet, amount, balance before/after for both sides,
status, reason, created_by, approved_by, related player/agent, game session, reversal link.
Corrections are REVERSAL entries (one per original). Gold and Chips histories are separate
(GET wallet/transactions?currency=GD|CH; mobile Transactions has All / Gold / Chips tabs).LedgerService::transfer() runs in a DB transaction, locks wallets with SELECT … FOR UPDATE
in id order, refuses negative balances and frozen sources, and is idempotent (same key → same
transaction; same key with different parameters → 409) — so every deduction and win is processed once.FEATURE_DAILY_CHIPS_REWARD, DAILY_CHIPS_REWARD_AMOUNT), and Single Player Gold (house reserves and the
Out of Gold claim).php artisan pusoy:reconcile (daily) checks every balance against the ledger and that escrow
equals active holds + room carry-over banks + held Single Player reserves.user.{id} channel
(wallet.updated); the mobile app also reloads balances after every deal / settlement / claim / leave
(pusoy:wallet window event), on Multiplayer game steps, on lobby changes and when the app returns to the
foreground. Home, the Lobby, Choose Your Seat, the Multiplayer table, the Single Player table, Profile and
Wallet all read the server (useBalance for Chips, useGoldWallet for Gold's Total Amount).Allocation workflow (Chips): Super Admin → Admin/Agent allocation wallet (or a player) → Agent → own
players. Records in wallet_allocations; manual credits/debits (Gold or Chips) in wallet_adjustments.
9 9 K vs Middle 9 9 K 4 3 → equal → valid.422 foul); rooms may set allow_foul_submission to accept them.
A fouled hand loses all three comparisons against every non-fouled opponent; two fouled
players tie each other (0). Timeout policy foul marks missing hands as fouled.auto_arrange (default) uses AutoArranger (best Back of 13, best Middle of
remaining 8, rest Front — always valid).random_bytes; deck = Fisher–Yates driven by
HMAC-SHA256(seed, counter) with rejection sampling. deck_commitment = sha256(seedHex|deck) is
published at the deal; the seed (stored encrypted) is revealed after completion so anyone can
verify (App\Game\Deck::verify).table: WAITING_FOR_PLAYERS → READY (4 seated) → IN_GAME → CLOSED
session: DEALING → ARRANGING → SUBMITTED → REVEALING → SCORING → COMPLETED
(any non-final) → CANCELLED (all entries refunded, no commissions)
Joining reserves the entry (GAME_ENTRY player → escrow, wallet_holds). Leaving before the deal
refunds it. The game deals when 4 seated players are ready; unready players on a full table are
removed and refunded after GAME_READY_TIMEOUT_SECONDS. Every transition locks the session/table
row and re-checks state, so duplicate requests, retried jobs and the sweeper are safe.
ResolveGameSession (unique job) reveals → scores → settles → completes; on settlement failure the
session stays in SCORING, the settlement is marked failed with the error, and the job /
pusoy:sweep / admin "retry" resume it.
Winner Takes All — fee = floor(pot × fee_bps / 10000); net = pot + carry_in − fee goes to
the top scorer. Ties per room tie_handling: split_equally (remainder minor units one each in
seat order), carry_forward (net held in the room bank for the next game), or tie_breaker
(best Back, then Middle, then Front; still tied → split). Fee is attributed equally to the four
players for commission purposes.
Round Bank (initial cumulative bank strategy) — entries are pooled; each player receives
entry + score × point_value (point value capped at entry / 9, so nobody loses more than their
entry and the bank always balances). Platform fee is fee_bps of each winner's gain,
attributed to that winner. Strategy classes: app/Game/Payout/*; each result asserts
Σpayouts + fee + carry_out = pot + carry_in.
Players cannot choose payout modes. Player-created private rooms play for Chips, fee-free, and use
PRIVATE_ROOM_PAYOUT_MODE.
These two payout modes belong to classic rooms (game_mode = classic). The seeded classic
pooled-bank room is now called "Points Bank" so it is not confused with the Round Bank game mode below.
game_rooms.game_mode)| game_mode | Who banks | Match |
| --- | --- | --- |
| classic | nobody — 4 players, pairwise ±1 scoring, payout mode decides the pot | one deal |
| round_bank | rotates by seat after every round (first eligible seat starts; never the same player twice in a row while someone else is eligible) | rounds_total rounds (12) |
| banker | the table creator (player who hosts, or first to sit at an admin room) every round | rounds_total rounds (12) |
A match is one game_tables row; each round is one game_sessions row (round_number,
banker_user_id). Service: App\Services\Game\BankerMatchService; pure maths:
App\Game\Banker\BankerRound; Lucky Hands: App\Game\LuckyHand.
Round flow: BETTING → ARRANGING → SUBMITTED → REVEALING → SCORING → COMPLETED, then an
intermission (BANKER_INTERMISSION_SECONDS, 8) and the next round (StartNextRound job; the
sweep is the safety net). The match ends after the last round, when fewer than 2 eligible
players remain, if nobody bets, or if staff cancel a round (that round is refunded; earlier rounds
stay settled). Hosted rooms are retired with their table.
min_players, default 2) and everyone ready. Players may join a
running match while a seat is free; they are dealt in from the next round.Then run powershell -ExecutionPolicy Bypass -File .\setup.ps1. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: winget install Git.Git
git clone https://github.com/aioz-stack/553.git cd 553
Node.js LTS (no version pinned), PHP ^8.3
winget install CoreyButler.NVMforWindows nvm install lts nvm use lts scoop install php composer # needs scoop: https://scoop.sh
Fill in secrets: APP_KEY, DB_PASSWORD, REDIS_PASSWORD, MAIL_PASSWORD, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, REVERB_APP_KEY, REVERB_APP_SECRET
Copy-Item .env.example .env
npm ci composer install
php artisan key:generate php artisan migrate
Run each command in its own terminal.
npm run dev php artisan serve
npm test
composer setup # composer install, .env, key:generate, migrate, npm install, npm run build
composer dev # runs server + queue + vite concurrently
Or step by step:
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
npm install
npm run dev
Then open http://localhost:8000.
No reports for Windows yet.
GitManual AI Agent reads the 7 key files and writes a step-by-step guide for Windows. Once written, it's saved for everyone.