khairul-anik-qp/qpbd-office

1. This is a pnpm workspace monorepo with three meaningful boundaries: apps/web for the PWA frontend, apps/api for the NestJS backend, and packages/shared for domain logic and shared constants/types used by both sides.

2. packages/shared is the domain contract layer. It contains request/status enums, user types, location/type constants, assignment helpers, operating-window logic, staff-count logic, and shared icon mappings. Both web and API import from here, so architecture diagrams should show it as the source of truth for cross-cutting business rules.

3. The backend is a NestJS 10 application in apps/api. It is organized by feature modules: auth, users, admin, staff, requests, assignment, SSE, push, reminders, email, and Prisma access. The backend owns all persistence, authorization, routing decisions, notifications, and background maintenance.

4. PostgreSQL is the primary system of record. Prisma sits between the API and the database, with migrations defining schema evolution for users, requests, push subscriptions, availability timestamps, favorites, cancellation/discard state, and related request lifecycle fields.

5. Authentication is Google OAuth plus JWT. The frontend sends Google sign-in credentials to /api/auth/google, receives a session token for active users, and routes based on role. New users are created as pending and must be approved or registered before accessing employee/staff areas.

6. The frontend is a React 19/Vite PWA in apps/web, split into role-specific shells: employee, staff, and admin. These shells are lazy-loaded UI boundaries that map directly to the three user roles and their workflows, rather than a single generic app screen.

7. Real-time updates use two channels: REST for commands and SSE for live state changes. The backend exposes /sse/events, and the web app has hooks and stores for SSE connection state, request synchronization, pending counts, and tab badges. Architecture diagrams should show SSE as a push-only event stream from API to clients, not a bidirectional socket.

8. Push notifications are a separate delivery path from SSE. The API stores push subscriptions and can send Web Push / FCM notifications, while the staff UI has setup and prompt components for enabling notifications. This matters because staff updates arrive both in-browser and out-of-browser.

9. The request lifecycle is the core business flow. Employees create requests through the web UI; the assignment service picks a staff target; staff accept, forward, and complete requests; the employee view reflects status changes live. The request states include new, progress, done, and discarded, with midnight auto-discard for stale open requests within the configured operating window.

10. Staff availability is its own subsystem because it affects routing and visibility. The API exposes staff roster and availability updates, and includes auto-reset/reminder services for busy status and stale “new” items. The frontend staff shell is organized around tabs for New, In progress, and Done.

11. There is an admin approval workflow for onboarding. Admin endpoints expose a pending queue and approval/rejection actions, while the admin UI shows the queue and staff/profile setup. Bootstrap admins are created from BOOTSTRAP_ADMIN_EMAILS on first login, which is an operational backdoor for initial setup.

12. Deployment is designed for single-origin production. The built web app is served alongside the API container, with Caddy and Docker Compose used for production orchestration. In development, Vite proxies /api and /sse to the API, so the browser still experiences one logical application surface.

13. Background jobs are part of the backend, not the frontend. The reminders service, request expiry service, and availability reset service run server-side to enforce time-based workflow rules independent of active clients.

14. The main diagram should therefore show four layers: browser/PWA shells, NestJS feature modules, Prisma/PostgreSQL, and external services such as Google OAuth, push providers, and optional email delivery. The key data flows are sign-in, request creation and status changes, live event broadcast, and notification delivery.