BILYART

ROADMAP

Build order (owner, 2026-09-30): server + admin first — 2, 3, 4, 5, 6, 7, 9 (server), 10, 12, 13, 14, 15 — then 8, 9 (tablet part), 11, 16.

Each phase = one or more PRs. Owner starts a phase by writing “Phase N ni boshla”. A phase is done only when all its checkboxes are true and CI is green.

Phase 1 — Inspect repo & hosting

• Repo skeleton: folders from CLAUDE.md §4, root README, .gitignore, .editorconfig
• [~] Owner answers the DEPLOYMENT.md §1 checklist — Tools screenshot + domain received; hostcheck report deferred to before Phase 16 (owner decision)
• Results recorded in DEPLOYMENT.md; ARCHITECTURE.md adjusted (portable DB, Laravel 13)
• List of open questions for the owner (domain, first flash method, tablet model) — see PROGRESS.md

Phase 2 — Architecture docs finalized

• ARCHITECTURE / DATABASE / SECURITY / DEVICE_PROTOCOL / DEPLOYMENT reviewed against SPEC.md, contradictions list confirmed with owner
• packages/protocol: JSON Schemas for device + tablet messages, generated TS types
• docs/API.md outline + OpenAPI file skeleton

Phase 3 — Database schema & migrations

• Laravel 13 app in apps/api, CI with MySQL 8 + MariaDB 10.6 + PostgreSQL services
• All migrations from DATABASE.md incl. composite FKs, generated table_lock unique column (partial unique index on PostgreSQL)
• Models + BelongsToTenant trait + factories
• Tests: cross-tenant FK insert fails at DB level; double active session insert fails at DB level

Phase 4 — Auth & multi-tenancy

• SPA session auth (same-origin, no Sanctum needed), login/logout/me, lockout, rate limits
• config/permissions.php, central middleware pipeline (policies for per-resource rules come with each feature)
• Idempotency middleware
• Error shape + log redaction
• Tests: spec §43 items 1–3, 13

Phase 5 — Super Admin

• API: tenants CRUD, suspend/activate/deactivate, payments, extend (both rules), set expiry, limits, subscription history, audit list, dashboard stats, platform settings
• web-admin: Super Admin area (mobile-first PWA)
• Tests: extend from active vs expired, limit change audit

Phase 6 — Client Admin

• Branches (LimitGuard), working hours, closed days, users & roles, pricing plans, tenant settings (+ tables CRUD, branch access restriction)
• web-admin client area (dashboard grows with sessions in Phase 7)
• Tests: spec §61 branch limit scenario (2 → denied → limit 3 → success), §43 item 7–8

Phase 7 — Tables & session engine

• Tables CRUD, SessionStateMachine, SessionService, PriceCalculator, working-hours check
• prepare/start/stop/complete, derived status, cron finalization, payment status marking (+ admin sessions, dashboard, daily/monthly reports, tablet kiosk read API)
• Tests: concurrency (parallel start → exactly one wins), duplicate Idempotency-Key, state transitions, pricing rounding

Phase 8 — Tablet app + kiosk shell

• Tablet pairing (code on screen → admin binds to branch)
• PWA screens, server-time offset, offline cache, countdown, warning audio (TTS + chime; uploaded clips: later, settings return mode: TTS)
• android-kiosk Kotlin shell — owner chose PWA only (2026-09-30); kiosk = Android App pinning, documented limitations
• docs/TABLET_SETUP.md (click-by-click; App pinning instead of QR provisioning)

Phase 9 — Photo capture & upload

• MediaPipe face detection → single capture, privacy notice (tablet PWA, Phase 8)
• Secure upload pipeline (validation, re-encode, private storage), authenticated viewing, deletion, retention job, access audit (server + web-admin viewer)
• Tests: spec §43 items 11–12

Phase 10 — Device service (server side)

• Device register/pairing/poll/ack/state endpoints, token auth, command bus + retry/expiry, online/offline (+ firmware releases for OTA, tablet pairing server side)
• START on session start, ACK → ACTIVE, no-ACK → FAILED + STOP
• Device simulator script (tests only) to exercise the protocol end-to-end (tests/Support/DeviceSimulator.php)
• Tests: spec §43 items 4, 10; poll endpoint performance check (≤ 6 queries per poll)

Phase 11 — ESP32 firmware

• Provisioning portal, pairing, pinned TLS, poll loop, commands, NVS session, local warning/OFF, watchdog, safe boot, OTA with rollback, diagnostics
• Native unit tests for session timing & command idempotency
• docs/ESP32_FLASHING.md, docs/HARDWARE.md (wiring diagram, relay/contactor sizing, electrician review note)
• One ESP32 per branch drives up to 8 table lamps (relay channel per table, owner decision 2026-10-01)
• On-hardware verification (needs a real ESP32 + relay module; checklist HARDWARE.md §5)

Phase 12 — Telegram

• Per-tenant bot setup, webhook with secret, chat linking, daily report per branch, alerts (device offline, session failed)
• Tests: tenant bot only sees own data; token never returned by API (§43 item 15)

Phase 13 — Subscription expiry & notifications

• Status transitions via cron, reminders 5/3/1/0 days (deduped), in-app + Telegram, expired lock-down behaviour (+ Super Admin notifications, owner data export)
• Tests: §43 items 5–6

Phase 14 — Monitoring, logging, backups

• /health, /health/db, /health/storage, /health/messaging (+ /health/backups), Super Admin health page
• Backup commands + verify + docs/BACKUP.md (restore proven on MySQL/MariaDB/PostgreSQL in CI)

Phase 15 — Security testing

• All spec §43 tests green, gitleaks clean, dependency audit (composer audit, npm audit), manual review checklist (TESTING.md, SECURITY_REVIEW.md)

Phase 16 — Production deployment

• Tooling ready (owner: deploy later): release package workflow, activate.sh/rollback.sh (tested install → update → rollback in CI), optional SSH deploy.yml, admin:create-super, click-by-click DEPLOY_UZ.md
• On the hosting: first install, cron configured, SSL, first Super Admin, smoke test (waits for the owner + hosting check results)
• Full spec §61 scenario on real hardware (incl. internet disconnect during session)
• Docs: SUPER_ADMIN_GUIDE, CLIENT_ADMIN_GUIDE, TROUBLESHOOTING (Uzbek versions for end users)