serkanfidanci/rastamanlonge

1. Overall shape

- This is a two-tier business system: a React/Vite frontend in the browser and a Node.js/Express backend API, backed by a single PostgreSQL 16 database.

- Deployment is containerized with Docker Compose: one app container and one Postgres container. There is no Supabase or external app server.

2. Client layer

- The frontend is a TypeScript React SPA (src/) with PWA support (sw.js, InstallPrompt.tsx, pwa.tsx), so users can install it like an app.

- The browser client handles customer booking flows, admin screens, and employee views, but all authoritative business actions are validated by the backend.

3. API / application layer

- The backend lives under server/ and is the main orchestration layer for all business rules.

- Key modules are split by concern: auth.js for JWT/bcrypt auth, db.js for Postgres access, whatsapp.js for notification transport, migrate.js and seed.js for startup database setup, and index.js as the server entrypoint.

- The backend is the boundary for booking validation, role checks, reporting, notification sending, and config management.

4. Authentication and role boundaries

- Auth is JWT-based with password hashing via bcrypt.

- The system distinguishes at least three access patterns:

- public/customer flows for booking and phone verification,

- admin flows for configuration, approvals, campaigns, and reporting,

- employee flows for seeing their own appointments and financial entries.

- The README makes clear that employees are restricted to their own records, while admins have system-wide visibility.

5. Core booking workflow

- Customers create appointments by selecting service, employee, date, and time.

- New appointments are stored as pending and later moved by admin to approved, rejected, cancelled, or completed states.

- Completion is a business event: completed appointments automatically generate revenue records in the finance ledger.

6. Finance and reporting

- Financial data is stored separately from appointments in finance_entries.

- The admin side can report on income, expenses, net profit, and employee-based performance.

- Employees can also add their own extra income/transaction records, so finance is not derived only from appointments.

7. Notification subsystem

- WhatsApp messaging is a first-class subsystem, not just a side effect.

- server/whatsapp.js abstracts provider delivery, supporting Meta WhatsApp Cloud API, a generic webhook provider, or a disabled mode.

- Every send attempt and failure is written to notification_logs, which makes notifications observable and auditable.

8. OTP and phone verification

- There is a dedicated public API for WhatsApp OTP request/verify and phone-verification checks.

- Verified phone state is remembered client-side for 180 days, but the server keeps only a hash of the verification key.

- This verification gate sits in front of the customer booking flow, so a booking cannot be created without a valid phone verification.

9. Campaign / discount engine

- Campaigns are stored and validated server-side, with rules for date, service, usage limits, and discount amount.

- Active campaigns are shown on the homepage, and booking can apply a campaign code.

- The backend re-validates the campaign at appointment creation time, so the discount used for booking is authoritative and reflected in finance records.

10. Employee scheduling and time off

- The schema includes employee_schedules, employee_timeoff, and employee_services, so availability is modeled explicitly rather than inferred.

- Hourly appointment slot logic and time-off constraints are handled in later migrations, which means scheduling is a backend-owned availability problem.

11. Persistence and schema evolution

- Database schema lives in db/migrations/ as numbered SQL migrations, starting with core tables and then adding feature slices like WhatsApp OTP, phone verification, campaigns, reminders, and campaign engine logic.

- Startup applies migrations automatically, and an initial admin account is seeded from environment variables.

- This indicates the database is the single source of truth for both operational data and system configuration.

12. Files, config, and deployment

- Employee profile photos are uploaded as files and persisted in a Docker volume, so they are separate from relational data.

- Sensitive settings such as JWT secret, encrypted WhatsApp token storage key, and provider credentials come from .env.

- The app is designed for local development and production Docker deployment, with the frontend and backend packaged together in the app container and PostgreSQL isolated in its own container.