Client Portal Business Guide

CLI-001

System Overview & Role

The Client portal gives the project owner a window into their projects. Clients can track progress, view published documents, browse site photos, raise support tickets, and view their payment ledger. They cannot modify any project data.

Capability	Source / filter
View projects	Project WHERE client_user_id = auth()->id()
Track progress	ProjectPhase across all client projects
View documents	ProjectDocument WHERE status=published
Browse gallery	GalleryItem WHERE visibility=client
Support tickets	SupportTicket WHERE client_user_id = auth()->id()
Financial ledger	LedgerEntry WHERE party_type=client AND party_id=auth()->id()
Notifications	AppNotification WHERE user_id = auth()->id()

CLI-002

Client Onboarding

A client user is created by the platform super_admin during tenant onboarding, or by the business admin inside the Admin portal. The client's user_id is then set on the relevant project's client_user_id field.

1Platform super_admin invites business → business admin account created

2Business admin creates client user account in the system

3Business admin creates project: POST /api/admin/projects with client_user_id

4Client user logs in → sees their project(s) immediately

5As work progresses, admin publishes documents and gallery items for client visibility

⚠ A client can only see projects where client_user_id matches their user ID. One client user can be linked to multiple projects.

CLI-003

Document Visibility Rules

Document status	Client sees it?	When admin uses it
draft	No	Document being drafted
pending	No	Awaiting internal approval
approved	No	Approved internally; not yet for client
published	Yes	Ready for client to download
rejected	No	Internal use; not suitable for client

Documents with requires_approval: true (from DocumentType) must be internally approved before they are published. Admin controls the final status: published transition.

CLI-004

Gallery Visibility Rules

visibility value	Who sees it
internal	Admin and staff only
client	Client + admin/staff
public	All portals (if applicable)

Admin sets visibility per GalleryItem. Only items with visibility = client appear in GET /api/client/gallery. This lets the admin curate what the client sees.

CLI-005

Support Ticket Flow

1Client raises ticket: POST /api/client/support → status: open

2Admin sees ticket in their system (future endpoint)

3Admin responds → status moves to in_progress

4Issue resolved → status moves to closed

5Client can view all their tickets but cannot close or delete them

CLI-006

Financial Ledger for Clients

The client ledger shows the financial relationship between the client and the business. The accounting perspective:

entry_type	Debit	Credit	Meaning
invoice	0	amount	Business issued an invoice to client; client owes this amount
payment	amount	0	Client made a payment; reduces outstanding balance
refund	0	amount	Business returned money to client
adjustment	varies	varies	Manual correction

// Outstanding balance (client owes business)
credits = SUM(credit) WHERE entry_type IN (invoice, adjustment_credit)
debits = SUM(debit) WHERE entry_type = payment
balance_due = credits - debits
// Positive = client still owes money; negative = overpaid

CLI-007

Error Reference

Code	Cause
401	Token missing or expired
403	user_type is not client
422	Validation failed on support ticket creation