WhatsApp Ticketing System — Product scope & user guide

Silicon Support · Self-hosted real-time support (WhatsApp, web chat, email channels)
Document version: April 16, 2026 · See also PRD v2 (markdown)

1. Scope summary

The system turns inbound WhatsApp (and other channel) messages into structured tickets with a React dashboard for agents, a Node/ Fastify API with Socket.IO, and PostgreSQL (self-hosted Supabase stack in Docker). Admins manage users, audit logs, and channels; staff agents handle tickets and contacts; company portal users see a reduced UI focused on their organisation’s tickets.

2. Roles: Admin, staff user, and company portal user

Role	Typical use	Navigation (high level)
`admin`	Full control: users, audit, channels, companies, settings, OpenAI keys (in-app).	Dashboard, Tickets, Contacts, Channels, Companies, Admin (Users, Audit Log), Settings.
`user` (staff)	Agents: tickets, contacts, channels, companies; no user management or audit log.	Same as admin except no Admin section (Users, Audit Log).
`company_user`	Customer org users via web portal (not WhatsApp).	Dashboard and Tickets only; no Contacts, Channels, Companies, Settings, or Admin.

3. User guide

3.1 Sign in

Open http://localhost:3000/login (or your production URL). Enter email and password, then Sign in. The default seeded admin (when using Docker defaults) is documented in the project README.

Sign-in page: Silicon Support branding, email and password fields — Figure 1 — Login at `/login` (Silicon Support).

3.2 Admin view — dashboard

After signing in as an admin, the sidebar shows the full staff menu plus the Admin section (Users, Audit Log). The dashboard summarises open tickets, priority, due today, channel status, and recent tickets.

Admin dashboard with metrics and sidebar including Admin section — Figure 2 — Admin dashboard (`/`) with Admin navigation visible.

3.3 Admin view — user management

Under Admin → Users, create users and switch roles between User and Admin; deactivate or reactivate accounts.

User management list with role dropdowns and status — Figure 3 — User management (`/admin/users`), admin only.

3.4 Staff user view

Staff with role user use the same dashboard and ticket workflows as admins, but the sidebar does not include Users or Audit Log. A dedicated screenshot for a non-admin session was not captured in this pass (see To-do below); behaviour is defined in the application routes.

3.5 Tickets and channels (staff)

Open Tickets for the queue; open a row for the conversation thread. Use Channels to add WhatsApp numbers (QR pairing), email, and web chat.

Tickets list with search and filters — Figure 4 — Tickets (`/tickets`), captured from `http://localhost:3000`.

Channel detail: name, alerts, onboarding, AI — Figure 5 — Channel detail (example WhatsApp channel), captured from `http://localhost:3000`.

3.6 Company portal user

Portal accounts are created under Companies (staff). Those users sign in at the same /login URL but see only Dashboard and Tickets. Messaging uses the portal API; see README for POST /api/v1/portal/messages.

4. Deployment

4.1 Linux / macOS (Git + Docker)

Copy .env.example to .env and configure secrets (see README).
From the repository root: docker compose up --build (or use deploy.sh).
Seed admin: docker compose exec api npm run seed (defaults in README).
Optional: ./deploy.sh migrate or MIGRATE=1 ./deploy.sh to apply supabase/migrations/*.sql to the running db container after deploy (existing DBs).

4.2 Windows (one-click)

deploy.bat — double-click for pull, build, and docker compose up -d --build --force-recreate.
deploy.bat migrate — same as above, then runs SQL migrations against Postgres.
deploy-with-migrate.bat — shortcut for deploy + migrate.
set FULL_REBUILD=1 before running for a clean image rebuild; set NO_PAUSE=1 to skip the closing pause for scripts.

After containers are up, configure platform and account options in the web app (OpenAI key in the database, appearance, password).

Figure 6 — Settings (/settings) after deployment, captured from http://localhost:3000.

4.3 Service URLs (local Docker defaults)

App	`http://localhost:3000`
API	`http://localhost:3001`
Supabase Studio	`http://localhost:8002` (mapped from container port; see `docker-compose.yml`)

5. To-do / follow-ups

Add a staff (user role) dashboard screenshot after login with a known non-admin test account (password not verified in this session).
Add a company portal user screenshot (sidebar with only Dashboard + Tickets).
Keep migration notes aligned with README: on some DBs, use supabase_admin instead of postgres for psql when objects are owned by Supabase roles.
Export this HTML to PDF if a formal client deliverable is required (print stylesheet not included).

Generated for internal documentation. Screenshots Figures 1–6 captured from http://localhost:3000 during authoring.