The Design Registry

13 — Client Portal, Approvals & Project Experience

Version: 1.0
Prepared: August 2026
Status: Engineering and product source of truth
Depends on: Product Vision; Spec 03 Teammates, Teams, Role Labels & Notifications; Spec 04 Workspace Dashboard & Profiles; Spec 05 Provider Applications; Spec 06 Proposals, Work Orders, Invoicing & Payments; Spec 07 Projects, Calendar, Items, Budgets & Provider Operations; Spec 08 Permissions; Spec 09 Pipeline, Forms & Automation Builder; Spec 10 Matchmaking, Offers & Network Assignment Engine; Spec 11 Communications; Spec 12 Tasks, Calendar, Resource Scheduling & Project Time Tracking

1. Executive Summary

The Client Portal is the calm, premium and guided side of The Design Registry. It gives a client everything needed to understand and advance a design Project without exposing the operational complexity used by designers, Registry staff and providers.

The portal must answer four questions immediately:

What has changed?
What needs my decision or action?
What happens next?
What has been approved, committed or paid?

The portal is not a separate product implementation. It is a permission-filtered client experience over the platform’s canonical Projects, decisions, approvals, items, budgets, Proposals, contracts, invoices, payments, Tasks, Calendar, communications and files. A designer publishing a presentation, requesting an item approval, proposing a meeting or sending an invoice must create one canonical record that appears in the appropriate designer, Registry and client surfaces. The platform must not copy or manually synchronize client versions of those records.

The experience should feel closer to a private project concierge than a CRM. It uses plain language, curated content, generous spacing, elegant black-and-white styling, strong photography and restrained status indicators. Internal pipeline stages, provider negotiations, margins, task queues, health scores and system terminology remain hidden.

The Client Portal must support single homeowners, couples, family members, assistants, financial representatives and other authorized decision-makers. Each person has an individual login, identity and audit trail. Formal decisions and commercial acceptances are attributable to the exact user and exact version reviewed.

2. Product Outcomes

The module succeeds when it:

gives clients confidence without requiring frequent status emails;
makes the next required client action unmistakable;
reduces approval delays and ambiguity;
presents Projects, documents, selections and finances in a premium manner;
lets designers publish once and reuse the same controlled record everywhere;
preserves a defensible history of decisions, acceptances and payments;
protects internal work, provider identities where hidden, negotiated economics and private communications;
works beautifully on mobile because many clients will review updates from email or SMS links;
lets multiple client participants collaborate without confusing authority;
supports designer workspace branding without weakening The Design Registry’s security and audit controls.

2.1 Success measures

At least 80% of formal client decisions are completed in the portal rather than captured manually.
Median time from approval request to recorded decision decreases over successive Projects.
At least 90% of active clients can identify their next action from the dashboard without opening the Project timeline.
Fewer than 1% of accepted decisions require administrative correction due to version or identity ambiguity.
No verified incident exposes internal notes, provider comparisons, negotiated costs, Registry economics or another client’s records.
Client notification links open the intended record after authentication and return the client to their prior context.

3. Scope

3.1 In scope

Client Workspace and individual client membership lifecycle.
Client dashboard and navigation.
Client Project profile and curated timeline.
Client actions, Decisions and Approvals.
Design presentations, selections and revision requests.
Client-facing items, budgets and allowances.
Proposals, contracts, invoices, payments and receipts.
Meetings, appointments, delivery and installation visibility.
Client messaging and published communications.
Published files, deliverables and version history.
Client roles and authority.
Branding and workspace personalization.
Notification Builder events and templates.
AI-assisted client summaries and support.
Mobile, accessibility, security, audit and analytics.
Migration of existing client records into the new model.

3.2 Out of scope

Internal designer Project management.
Provider bid comparison and awarding.
Provider portals and operational resource scheduling.
Payment processing implementation details owned by Spec 06.
General authentication implementation owned by the authentication specification.
Detailed messaging transport owned by Spec 11.
Native mobile applications; this specification requires a responsive web experience and installable-web readiness.

4. Product Principles

4.1 Curated, not simplified by duplication

Clients see curated projections of canonical records. The platform never creates a manually maintained “client copy” of a Project, invoice, file or approval.

4.2 Publish intentionally

Internal work stays internal until an authorized user publishes or shares it. Draft visibility cannot be inferred from record existence.

4.3 Formal actions are explicit

A chat reply, email reaction or comment is not a formal approval when the workflow requires an approval, Proposal acceptance, signature or payment authorization.

4.4 Exact-version integrity

Every formal client decision references the exact content, file, selection, amount and terms reviewed. Later edits never mutate the accepted version.

4.5 Calm by default

The portal highlights the client’s decisions and meaningful progress. It does not surface internal operational noise, every task update or every provider movement.

4.6 Individual identity

Shared household email accounts are discouraged. Every action is attributable to a user. Multiple people can belong to one Client Workspace with distinct authority.

4.7 Mobile first for action

Notification links, approvals, messages, invoice review and appointment responses must be effortless on a phone.

4.8 Build once, reuse everywhere

Cards, grids, document viewers, forms, date pickers, file galleries, conversations, financial summaries and activity components use the same design system as the authenticated platform.

5. Client Domain Model

5.1 Client entity

A Client entity represents the customer relationship. It can exist as a passive CRM record before login access is granted. It contains contacts, relationship metadata, Project relationships and controlled profile information.

5.2 Client Workspace

A Client Workspace is provisioned when portal access is required. It contains memberships, branding context, notification preferences and access to one or more authorized Projects. A Workspace may represent an individual, household, family office or organization.

5.3 Client user

A client user is an individual authenticated identity. A user can belong to more than one Client Workspace only through explicit invitations and must select the active Workspace when context is ambiguous.

5.4 Project relationship

Project access is granted through a client–Project relationship with effective dates, status and allowed audience. A Client Workspace does not automatically gain access to every Project associated with a similar name, address or email.

5.5 Client action

A Client Action is a guided request to complete something: upload a file, confirm access, respond to an appointment or review a formal Decision. It may reference a shared Task, but formal approvals remain separate governed records.

5.6 Decision and approval

A Decision presents a defined question, options, recommendation where appropriate, impact, due date, decision authority and immutable review snapshot. An Approval is the governed response to that Decision or another versioned record.

5.7 Published artifact

A Project file, presentation, budget view, selection set, milestone or update becomes client-visible through an audience-controlled published artifact or canonical record state. Publication records who published it, when and what version was visible.

6. Client Lifecycle

6.1 Pre-portal state

A client may exist as a lead, Project Opportunity contact or passive entity. No login exists and no portal notification may be sent until an authorized user starts the invitation flow.

6.2 Invitation

The invitation flow:

Selects or confirms the Client entity and Project relationship.
Enters the recipient’s name, email and intended Client role.
Previews exactly which Projects and capabilities will be available.
Selects the sender identity and invitation template.
Sends a single-use, expiring invitation.
Requires account authentication and acceptance of applicable terms.
Records activation, inviter and invitation scope.

An invitation must not reveal Project detail before identity verification. Resend, revoke and expiry actions are audited.

6.3 Activation states

not invited;
invitation pending;
active;
suspended;
access ended;
archived.

Suspension stops portal access but preserves history. Ending access does not remove the person’s attributable past decisions.

6.4 Adding another client participant

Only an authorized designer/admin or a Client Decision Maker with delegated invite capability may request another participant. The system shows the proposed role and Project access before sending. High-authority roles may require designer confirmation.

6.5 Project completion and aftercare

After completion, the portal can enter an archive/aftercare state containing final documents, warranties, receipts, approved photography, care information, unresolved deficiencies and permitted messages. Edit and approval actions narrow according to Project status.

7. Client Roles and Authority

Starter roles are defined by Spec 08 and remain customizable within safe boundaries.

7.1 Client Decision Maker

May receive formal approvals, accept Proposals, sign where configured, view permitted financials, respond to appointments and access published Project material. Financial and commercial authority may still be limited by policy.

7.2 Client Collaborator

May view shared information, comment, upload files, respond to personal appointments and submit preferences. Approval, payment and signature authority are separately configurable.

7.3 Client View Only

May view curated status, selected files, published schedule and messages. Cannot make formal Decisions.

7.4 Specialized authority

Optional authority can be granted for:

design approvals;
item selections;
budget variance;
Proposal/contract acceptance;
invoice/payment actions;
site access and scheduling;
photography/publication consent;
participant invitations.

7.5 Multiple decision-makers

A Decision policy may require one named decision-maker, any authorized decision-maker, unanimous approval, a minimum count or ordered approval. The UI clearly states who must respond and whether the outcome is final. Conflicting responses place the Decision in conflict or needs_resolution; the system never chooses silently.

7.6 Delegation and absence

Temporary delegation includes scope, start/end time and granting authority. It cannot grant more power than the delegator has. Sensitive commercial delegation may require designer approval and stronger authentication.

8. Information Architecture

The default Client Portal navigation is:

Home
Projects
Decisions
Messages
Calendar
Files
Proposals & Payments
Profile

Navigation items disappear when the user lacks any eligible records, but direct URLs still enforce server-side access. On mobile, Home, Projects, Decisions and Messages remain primary; the rest live under More.

8.2 Multi-Project clients

Home aggregates permitted actions across Projects. Every card identifies its Project. The Project switcher never shows Projects outside the active Client Workspace.

A client Project profile uses:

Overview
Timeline
Decisions & Selections
Budget
Calendar
Messages
Files
Proposals & Payments

Delivery, installation and aftercare appear contextually in Overview/Timeline and may become a focused view when active. Internal Tasks, Providers, commercial sourcing and operational tabs do not appear.

9. Client Home Dashboard

9.1 Experience objective

The dashboard feels like a premium concierge briefing. It is calm when nothing is required and direct when action is needed.

Personalized greeting.
Active Project or portfolio context.
Designer/studio branding and primary contact.
Notification indicator.
Optional Project hero image.

9.3 Module priority

Modules appear in this order when relevant:

Action required — Decisions, signatures, payments, uploads and appointment responses.
What’s next — Next milestone, meeting, delivery or installation.
Project progress — Curated phase and recently published update.
Recent changes — New presentation, approved item, schedule change or payment receipt.
Messages — Unread authorized conversations.
Financial summary — Approved budget, upcoming request and payment state when permitted.
Published files — Latest deliverables.

9.4 Action cards

Each action card shows Project, plain-language request, due date, requester, expected time, consequence of delay where appropriate and one primary action. It does not expose internal priority, SLA or queue labels.

9.5 Empty and calm states

When no action is needed, show a reassuring current status, next known milestone and contact path. Do not fill the page with artificial activity.

10. Client Project Overview

10.1 Header

Project name and client-safe site.
Designer/studio.
Current client-facing phase.
Project status.
Next meaningful milestone.
Primary client contact/action.
Project image/gallery where published.

10.2 Client-facing phase model

The canonical seven stages remain Concept, Design, Design Package, Construction Administration, Decorating, Procurement and Installation. Client labels and descriptions may be customized, but map to stable phase IDs. Overlapping phases must be presented truthfully without making the process appear broken.

10.3 Overview cards

Current focus and latest update.
Decisions needed.
Upcoming dates.
Approved selections and open selections.
Client-visible budget summary.
Procurement/delivery highlights.
Files and presentations.
Messages.

10.4 Progress

Progress derives from published milestones and required approvals. It is never manually typed. Internal health, resource risk and provider performance remain hidden; authorized users can publish a client-safe delay or risk update.

10.5 Project updates

An authorized Project team member may publish a structured update containing summary, completed highlights, current work, upcoming work, client actions, approved images and client-safe risks. Draft and published versions are distinct. Publishing can notify selected client roles.

11. Curated Timeline

The Timeline combines client-visible milestones, Decisions, appointments, Proposal/invoice events, published files, delivery/install events and Project updates.

11.1 Timeline controls

All activity;
Updates;
Decisions;
Meetings;
Financial;
Delivery & Installation;
Files.

11.2 Event language

Events use plain language such as “Concept presentation ready for review,” not internal event keys. Each event deep-links to the canonical record if the client has access.

11.3 Exclusions

Never show internal notes, task reassignment, provider shortlist activity, private emails, bid comparison, internal status changes, margin, commissions, referral fees, staff performance or hidden provider identities.

12. Decisions and Approvals

12.1 Decision types

design direction;
presentation/version approval;
item or selection approval;
budget or allowance variance;
schedule/date confirmation;
change scope acknowledgement;
photography/publication consent;
Proposal/contract acceptance reference;
other configurable typed Decisions.

Commercial acceptances continue to use Spec 06’s governed records even when launched from Decisions.

12.2 Decision record

Fields include:

Project and phase;
title and plain-language question;
decision type;
requester;
decision-maker policy;
due date and time zone;
options and recommendation;
design, budget and schedule impact;
linked items, rooms, files, presentation or commercial version;
immutable review snapshot;
allowed responses;
comments and revision request rules;
result and effective time;
superseded/withdrawn state;
audit metadata.

12.3 Decision states

Draft, scheduled, published, viewed, partially responded, approved, declined, changes requested, conflict, withdrawn, superseded and expired.

12.4 Review screen

The client sees:

What is being decided.
The current version and supporting material.
Recommendation and alternatives where shared.
Financial and schedule impact.
Who is required to respond.
Due date and consequence of delay.
Comment/revision controls.
A clear final confirmation.

High-impact Decisions require a dedicated confirmation screen and reauthentication or step-up verification according to policy. The final button states the effect, such as Approve design package v3 or Accept proposal for $42,000.

12.5 Request changes

A client can request changes with a required comment and optional markup/reference. This does not edit the reviewed version. It closes or pauses the Decision according to workflow and creates a linked revision request for the Project team.

12.6 Superseding

If content changes materially after publication, the prior Decision is withdrawn/superseded and a new version is issued. Prior responses remain readable but no longer govern the new version.

12.7 Reminders and escalation

Reminder schedules are configured in the Notification Builder. Overdue Decisions appear on designer and client dashboards. Escalation communicates schedule impact without revealing internal SLA or blame.

13. Presentations, Design Reviews and Selections

13.1 Presentation package

A presentation package can contain cover, narrative, rooms, images, floor plans, material palettes, item selections, alternatives, budget context and required Decisions. It is an immutable published version.

13.2 Viewing experience

Full-screen and page/section navigation.
Responsive image and document viewer.
Room/area grouping.
Optional side-by-side alternatives.
Zoom and accessible text descriptions.
Comment at package, page, room or item level where enabled.
Visible version and publication date.
Download only when allowed.

13.3 Selections

Client-visible item cards may show image, name, category, room, description, selected option, quantity, client-facing unit/total price, allowance/variance, lead-time summary and approval state. Internal vendor source, trade pricing, margin and provider communications remain hidden unless explicitly configured.

13.4 Group approvals

Selections can be approved individually or as a defined selection set. The review screen explains whether approval authorizes purchasing. Bulk approval is allowed only for a fixed version and displays the total financial impact.

13.5 Alternatives

Alternatives preserve the recommended option and comparison dimensions. Choosing an alternative does not silently approve the order if a separate financial or purchasing authorization is required.

13.6 Comments versus Decisions

Comments support discussion. Only the formal Decision action changes approval state. The UI visibly distinguishes the two.

14. Client Budget Experience

14.1 Visibility policy

Budget access is separately permissioned. The Project team configures which measures and categories are client-visible. Hidden cost, markup, commission, referral economics and provider price comparisons are excluded.

14.2 Summary

When authorized, show:

approved Project budget;
committed amount;
paid amount;
forecast client total;
remaining/unallocated amount;
client-approved changes;
allowances and known variances;
category/room breakdown.

Every total identifies its as-of time, currency and inclusion rules.

14.3 Drilldown

Clients can drill into permitted categories and items. Calculated totals link to the underlying client-visible sources. Internal cost components remain masked.

14.4 Variances and changes

A variance requiring approval creates a formal Decision with original amount, proposed amount, difference, reason, schedule effect and affected scope. Approval does not replace a Change Order where commercial rules require one.

14.5 Currency and taxes

Currency, taxes, deposits, discounts and allowances follow canonical commercial rules. Mixed-currency Projects show conversion source/date and never imply final settlement from estimates.

15. Proposals, Contracts, Invoices and Payments

15.1 Shared commercial records

The portal displays the exact immutable versions owned by Spec 06. It must not generate separate client versions.

15.2 Proposals and contracts

Clients can:

review versioned scope, fees, allowances, exclusions and payment schedule;
ask a question linked to the document;
accept, decline or request revision when allowed;
sign through the configured signature flow;
download an accepted copy;
view amendments and Change Orders.

15.3 Invoices

Invoice views show number, issuer, Project, issue/due date, line summary, tax, amount due, payment state, instructions and supporting documents. Provider/Registry internal lineage is hidden.

15.4 Payments

Supported actions depend on configuration and amount:

Stripe payment where eligible;
manual bank-payment instructions;
upload or submit remittance information;
view pending, confirmed, failed, refunded or disputed state;
download receipt.

The portal never marks manual payment as settled solely from a client assertion. Reconciliation remains canonical.

15.5 Financial authority

Proposal acceptance, signature and payment capability are separately permissioned. Higher-risk actions may require step-up authentication. A collaborator can view an invoice without being able to pay it.

16. Calendar and Appointments

Clients see explicitly shared meetings, presentations, site access appointments, deliveries, installations and photography appointments.

16.1 Actions

Accept, tentatively accept or decline.
Request another time.
Add to an external calendar.
View location, virtual link and client-safe instructions.
Confirm site access, parking, pets, elevator or other requested information.
Receive reminders.

16.2 Privacy

Clients do not see internal resources, crew utilization, private attendees, provider capacity or surrounding appointments. Hidden provider identities are represented by client-safe service labels.

16.3 Rescheduling

Confirmed appointments cannot be silently changed. Rescheduling shows prior and proposed time, reason, response requirement and resulting schedule impact where appropriate.

17. Procurement, Delivery and Installation

17.1 Client-safe procurement status

The Project team configures whether clients see selected, approved, ordered, in production, shipped, received, stored, scheduled or installed states. Detailed provider operations and warehouse locations remain hidden.

17.2 Exceptions

Damage, delay or failed delivery is not automatically exposed in operational form. An authorized team member publishes a client-safe exception/update when client awareness or Decision is required.

17.3 Delivery and installation view

When active, show:

confirmed date/window;
site preparation checklist;
access requirements;
client presence requirement;
broad progress status;
completion summary;
permitted photos and deficiencies;
next step.

Live vehicle location is shown only when configured and operationally appropriate. It never reveals other clients’ stops.

17.4 Deficiencies and aftercare

Client-visible deficiencies show description, room/item, acknowledged status, next step and target resolution. Internal assignment, provider fault analysis and cost recovery remain private.

18. Messages and Collaboration

18.1 Shared communications model

Client messages use Spec 11’s canonical Conversations. Project Messages are participant-facing; internal Notes never appear.

18.2 Client inbox

Conversation list scoped to authorized Projects.
Unread state.
Project and topic filters.
Attachments and previews.
Draft persistence.
Reply through in-app messaging and configured email bridging.
Deep links to related Decision, file, invoice, item or appointment.

18.3 Plain-language experience

Do not display queue names, routing tags, SLA, internal assignee presence, call disposition or provider relationship metadata. The client sees the person/studio identity appropriate to the conversation.

18.4 Formal-action boundary

A message such as “looks good” does not approve a design. The system can offer a secure link to the pending Decision. AI may detect apparent intent and prompt the Project team, but cannot convert a message into approval automatically.

18.5 Participants

Only authorized Project participants can be added. Client-to-provider direct messaging is disabled unless the governing Project relationship explicitly permits it.

19. Files and Deliverables

19.1 Published library

The Files area contains only published or explicitly shared files. It supports categories such as presentations, drawings, specifications, contracts, invoices, receipts, care/warranty documents, photos and client uploads.

19.2 File card

title and type;
Project, phase and room/area;
version and issue date;
publisher;
approval/signature state;
view/download controls;
superseded indicator;
related Decision or message.

19.3 Versioning

Issued and accepted versions are immutable. A current-version indicator does not erase historical versions the client previously reviewed. Superseded versions remain accessible when policy allows and are clearly labelled.

19.4 Client uploads

Clients can upload requested information into a defined request or permitted folder. Uploads are virus-scanned, access-controlled and attributed. They do not become published Project deliverables until reviewed.

19.5 Download controls

Download, print and share-link capability are configurable. Signed URLs are short-lived and permission-scoped. Revoked access invalidates future retrieval.

20. Client Profile and Preferences

20.1 Client Profile versus Client Portal

The Client Profile is the canonical Entity Profile used by authorized Registry and Designer Workspace users to manage the relationship. The Client Portal is the Client’s authenticated, permission-scoped projection of that Profile and its Projects. They are not separate Client records and must not drift.

The Clients directory must evolve from an Edit-only row into a dedicated Client Profile route. Selecting a Client name or Client ID opens the Profile rather than only a large modal.

20.2 Client Profile structure

The Client Profile reuses the shared Entity Profile shell and provides:

a header with Client ID, name, preferred contact, Relationship Owner, Portal state and permitted actions;
an Overview with household or organization relationships, addresses, contact consent, preferences, active work and next actions;
Project Opportunities and Projects with canonical labels and direct record links;
Matching Profile completeness, freshness, source and Project-specific overrides;
Decisions and Approvals;
Files, Tasks, Communication, Notes, Activity and History;
Portal invitations, Memberships, access state and revocation history;
duplicate detection, merge and survivorship controls.

Legacy Lead labels in the Clients directory, counts and links must be replaced by Project Opportunity or the applicable Pipeline Record. Financial and contact fields are permission-scoped in rows, Profiles, search and exports.

20.3 Client-managed preferences

Clients can manage:

name, pronouns and preferred display name;
permitted contact details;
password/authentication controls through Auth;
language, locale and time zone;
notification preferences;
accessibility preferences where supported;
appointment/contact preferences;
profile image;
consent and privacy settings;
authorized Workspace memberships.

Project addresses, legal billing details and decision authority are governed records and cannot be casually overwritten from the personal profile.

20.4 Relationship and data rules

One Client Entity may relate to many Project Opportunities and Projects.
A household, couple, assistant or organization contact uses explicit relationships rather than duplicate Client records.
A Project-specific preference or Decision does not silently overwrite durable Client facts.
Rooms, Services Needed, Designer Specialties and similar multi-value fields use the shared field registry with the correct multiplicity.
Internal Notes, hidden Provider identities, Match comparisons, margins and unrelated Projects never appear in the Client Portal.
Portal invitation, pending, active, suspended and revoked states remain visible and auditable on the Client Profile.

21. Branding and Personalization

21.1 Branding hierarchy

The Client Portal can display designer/studio logo, name, approved accent, Project imagery and client-facing sender identity. The Design Registry retains a discreet platform/security identity where required.

21.2 Workspace configuration

logo and wordmark;
black/white or restrained accent palette;
typography from approved tokens;
welcome message;
contact/support information;
email/logo treatment;
optional portal subdomain in a later integration phase.

21.3 Guardrails

Branding cannot reduce contrast, obscure security information, imitate another Workspace or alter formal record language in a misleading way. Layout and interaction remain standardized.

22. Notifications

Every client notification introduced here must be an editable Notification Builder template with in-app and configured Resend email/Twilio SMS variants.

Required events include:

Client invited, invitation expiring, accepted or revoked;
Project access granted, changed, suspended or ended;
Project update published;
Decision requested, reminder, changed, overdue, approved, declined, changes requested, withdrawn or superseded;
presentation/file published;
comment/message received or mentioned;
appointment proposed, confirmed, changed, declined, cancelled or starting soon;
Proposal/contract sent, expiring, accepted, declined or revised;
invoice issued, due soon, overdue, payment received, failed or refunded;
budget variance/change requires review;
delivery/installation scheduled, changed, starting or completed;
deficiency update;
final Project/aftercare package published.

Templates support Project/studio branding, secure action links, safe excerpts and preference controls. Sensitive content is summarized and linked rather than embedded in SMS. Mandatory commercial/security notices cannot be disabled. Digest rules prevent excessive notifications.

23. AI Client Concierge

23.1 Approved uses

summarize published Project status in plain language;
explain a client-visible term using approved Project context;
identify pending actions and dates;
summarize a presentation or document;
compare published selection alternatives;
draft a question or revision request;
answer navigation/support questions;
translate or simplify client-visible text;
create a draft Project update for designer review.

23.2 Source and confidence

Answers cite or link to the client-visible Project records used. If the answer is uncertain or the required information is private/unpublished, the concierge says so and offers to message the Project team.

23.3 Guardrails

AI cannot:

approve, sign, accept, pay or decline on the client’s behalf;
reveal internal notes, hidden providers, cost, margin or other clients;
invent dates, prices, selections or commitments;
treat informal chat as a formal Decision;
publish content without authorized review;
make legal, financial or construction assurances beyond approved records.

AI context is assembled after access and field filtering. Prompt/output audit follows platform policy.

24. Permissions and Visibility

Use Spec 08’s capabilities, field access, audience rules and RLS model.

24.1 Capability families

client_portal.access;
client_projects.view;
client_updates.view;
client_decisions.view/respond/comment;
client_selections.view/respond;
client_budget.view;
client_calendar.view/respond;
client_messages.view/send;
client_files.view/download/upload;
client_commercial.view/accept/sign/pay;
client_participants.view/invite/manage;
client_profile.manage_self.

24.2 Visibility classification

Canonical records use internal, Registry, designer, provider, client and specifically-shared audiences. “Client-visible” still requires Project relationship and capability; it is not public.

24.3 Never-visible defaults

internal notes and internal Tasks;
provider shortlist, bid comparisons and rejection reasons;
negotiated Provider rates and provider invoices;
Registry commissions, referral fees and margin;
internal cost and staff rates;
private contacts;
unpublished drafts;
internal health/risk scoring;
audit/security internals;
other clients and their activity.

24.4 Impersonation and support

Support impersonation requires explicit capability, reason, visible banner, limited duration and audit. High-risk actions are blocked while impersonating.

25. Data Model

Core tables extend the shared entity, membership and Project models:

client_entities
client_workspaces
client_workspace_memberships
client_project_relationships
client_invitations
client_delegations

client_actions
project_updates
project_update_versions
published_artifacts

decisions
decision_versions
decision_options
decision_participants
decision_responses
decision_requirements
decision_comments

presentation_packages
presentation_versions
presentation_sections
presentation_record_links
selection_sets
selection_set_versions

client_budget_views
client_budget_view_versions

client_portal_branding
client_notification_preferences
client_consents

Shared canonical tables remain authoritative for Projects, items, files, calendar events, conversations, Proposals, contracts, invoices, payments and activity.

25.1 Constraints

Every membership references one authenticated user and Client Workspace.
Every Project relationship has explicit scope and effective state.
Formal responses reference an immutable decision/version snapshot.
A user cannot respond outside their authority or after withdrawal/supersession.
Published artifacts reference immutable source versions where formal review applies.
Client budget views cannot expose protected cost components.
Invitation tokens are hashed, single-use and expiring.
Audience filtering occurs before search indexing, notifications, realtime and AI context.

26. Supabase Architecture

Supabase Auth supplies user identity and assurance state.
Postgres is canonical for memberships, Project relationships, decisions and publication records.
RLS enforces Workspace, Project and audience access on every client-facing table.
Explicit database grants remain separately configured from RLS.
Private Realtime channels deliver permitted messages, Decision changes and Project updates; database reads remain canonical.
Supabase Storage uses permission-scoped object metadata and signed URLs.
Edge/server functions perform privileged invitation, acceptance, payment handoff and publication workflows.
A transactional outbox publishes notification and activity events.
Rate limiting and abuse protection apply to invitation, login, message, upload, Decision and payment endpoints.
Audit correlation IDs connect client action, domain event and notification delivery.

No service-role credential is exposed to the browser. Authorization is recalculated server-side for every high-risk mutation.

27. API Design

27.1 Client session and workspace

GET  /v1/client/session
GET  /v1/client/workspaces
GET  /v1/client/workspaces/:workspaceId
GET  /v1/client/home
POST /v1/client/invitations/:token/accept
POST /v1/client/participants/invitations
POST /v1/client/workspaces/:workspaceId/switch

27.2 Projects and updates

GET  /v1/client/projects
GET  /v1/client/projects/:projectId
GET  /v1/client/projects/:projectId/timeline
GET  /v1/client/projects/:projectId/updates
GET  /v1/client/projects/:projectId/budget
GET  /v1/client/projects/:projectId/delivery-installation

27.3 Decisions and selections

GET  /v1/client/decisions
GET  /v1/client/decisions/:decisionId
POST /v1/client/decisions/:decisionId/respond
POST /v1/client/decisions/:decisionId/comments
GET  /v1/client/projects/:projectId/presentations
GET  /v1/client/selection-sets/:selectionSetId
POST /v1/client/selection-sets/:selectionSetId/respond

27.4 Shared modules

GET  /v1/client/calendar
POST /v1/client/events/:eventId/respond
GET  /v1/client/conversations
POST /v1/client/conversations/:conversationId/messages
GET  /v1/client/files
POST /v1/client/file-requests/:requestId/uploads
GET  /v1/client/commercial-documents
POST /v1/client/proposals/:proposalId/respond
POST /v1/client/invoices/:invoiceId/payment-session

All list endpoints use cursor pagination and stable sorting. Mutations accept idempotency keys and optimistic concurrency/version tokens. Error responses explain expired versions, missing authority and required next action without exposing private record existence.

28. Domain Events

Publish versioned events including:

client.invited, client.activated, client.access_changed, client.access_ended;
project_update.published;
decision.published, decision.viewed, decision.responded, decision.conflicted, decision.withdrawn, decision.superseded;
presentation.published, selection_set.published, selection.responded;
client_file.published, client_upload.received;
client_event.responded;
client_commercial.viewed, client_commercial.responded;
client_payment.started, client_payment.result_changed.

Events carry actor, Client Workspace, Project, subject/version, correlation ID and safe summary. Consumers independently authorize every follow-on action.

29. Search

Client search covers only permitted Project names, published updates, Decisions, client-visible items, files, messages and commercial documents. Results show type, Project and context. Search indexes are removed or updated promptly when access ends or publication is revoked.

Search never confirms the existence of hidden providers, drafts, internal messages, other clients or masked financial fields.

30. Activity and Audit

The client sees a curated activity timeline. The platform audit log separately records:

invitations and access changes;
authentication assurance for high-risk actions;
record views where policy requires;
publication and revocation;
Decision versions and responses;
Proposal/contract acceptance;
payment initiation/results;
downloads and sensitive exports;
delegation;
impersonation;
notification delivery.

Audit records are append-oriented and retained according to legal/commercial policy. Corrections create linked records rather than rewriting accepted history.

31. Mobile and Responsive Experience

All primary actions work at 320 CSS pixels without horizontal page scrolling.
Approval, invoice and document review use focused mobile layouts.
Sticky action bar may show the single governing action.
Large presentations support responsive sections and optional full document view.
Upload supports camera/photo library and progress recovery.
Notification deep links preserve intended destination through authentication.
Offline mode may cache previously viewed non-sensitive summaries under policy; formal actions require server confirmation.
Delivery/install day emphasizes schedule, instructions, status and contact.

32. Accessibility and Design System

Meet WCAG 2.2 AA.
Use semantic headings, landmarks and form labels.
Every image used for a Decision has meaningful alternative text or is marked decorative.
Colour never communicates approval or status alone.
Decision controls are keyboard and screen-reader accessible.
Documents provide accessible alternatives where possible.
Focus moves predictably through dialogs and returns to the trigger.
Error messages identify the field and resolution.
Currency, dates, time zones and numeric values are localized and unambiguous.
Motion is restrained and honors reduced-motion settings.
The portal uses the established black-and-white, elegant, rounded visual system with generous whitespace.

33. Privacy, Security and Compliance

Collect only client information needed for the relationship.
Consent records include purpose, version, time and actor.
Sensitive commercial actions use step-up authentication based on risk.
Session, invitation, upload and payment endpoints are rate-limited.
Files are scanned and served through scoped access.
Client data is excluded from AI training unless an explicit platform policy and consent permit it.
Exports obey access and watermarking policy.
Account recovery cannot grant access to an unverified Project relationship.
Notification content minimizes sensitive details.
Access removal revokes sessions/refresh where required and future signed links.

34. Analytics and Reporting

34.1 Product analytics

invitation activation rate;
dashboard and Project engagement;
Decision view/response time;
revision-request rate;
overdue client actions;
presentation completion;
appointment response rate;
Proposal/invoice view-to-action;
notification delivery and deep-link completion;
support requests and failed actions;
mobile versus desktop use.

34.2 Project team reporting

Designers see client response status, not invasive behavioral surveillance. Reports show who must respond, last permitted activity, reminders sent, decision result and blockers.

34.3 Privacy

Analytics avoid exposing message content, private files or unnecessary individual behavior. Access follows Workspace/Project permission.

35. Failure and Edge Cases

Invitation sent to wrong email: revoke before activation and audit.
Duplicate Client entities: merge through governed entity tooling without losing decisions.
Client changes email: verify new address; retain identity history.
Multiple decision-makers disagree: mark conflict and route resolution.
Decision version changes during review: reject stale submission and show new version.
Access ends during open session: next protected action/read fails safely.
Payment succeeds but webhook is delayed: show processing, reconcile idempotently.
File publication is revoked after notification: link shows unavailable, not hidden metadata.
Appointment changes while client responds: require current version.
Project team accidentally marks draft client-visible: publication workflow still requires explicit publish.
Client replies to notification email: route to canonical Conversation where enabled.
Client has no active Project: show archive/support state, not an empty CRM dashboard.

36. Migration Plan

36.1 Inventory

existing Clients and contacts;
Project/client relationships;
current client portal users if any;
shared files and links;
approvals captured in notes/email;
Proposals, invoices and payment records;
notification preferences and consent.

36.2 Normalize

deduplicate Client entities without destroying provenance;
separate contact identity from Client Workspace;
create explicit Project relationships;
map known decision-makers and collaborators;
classify existing files as internal, published or unknown;
never infer formal approval from ambiguous text.

36.3 Provision

create Client Workspaces only for intended portal users;
send fresh invitations rather than importing insecure credentials;
backfill access and publication records;
preserve accepted commercial document lineage.

36.4 Validate

compare permitted Project/file counts;
sample each role and multi-client scenario;
verify no internal notes/providers/economics appear;
confirm accepted versions and payments reconcile;
test revoked and expired access.

36.5 Rollout

Roll out behind feature flags by designer workspace and Project. Existing links receive safe redirects. Maintain read-only compatibility until portal access and commercial history are reconciled.

37. Implementation Phases

Phase 1 — Client identity and access

Client Workspace and memberships.
Invitations, activation and roles.
Project relationships and RLS.
Profile/preferences.

Phase 2 — Dashboard and Project experience

Home dashboard.
Project Overview and curated Timeline.
Project updates and publication workflow.
Responsive navigation and branding.

Phase 3 — Decisions, presentations and selections

Decision engine and immutable snapshots.
Presentation viewer.
Selection sets, comments and revision requests.
Multi-decision-maker policies.

Phase 4 — Shared collaboration

Messages.
Calendar responses.
Published files and client uploads.
Notification Builder templates.

Phase 5 — Budget and commercial

Client budget views.
Proposals/contracts.
Invoices, payment sessions and receipts.
Financial authority and step-up authentication.

Phase 6 — Delivery, installation and aftercare

Client-safe logistics status.
Delivery/install day experience.
Deficiencies, warranties and archive.

Phase 7 — Intelligence and optimization

AI Client Concierge.
Advanced analytics.
Personalization and controlled external integrations.

Each phase includes RLS tests, accessibility, mobile QA, notification validation, audit checks, migration rehearsal and rollback controls.

38. User Stories

38.1 Client Decision Maker

I can open the portal and immediately see what requires my decision.
I can review the exact design version, understand budget/schedule impact and approve confidently.
I can see what I have approved and when.
I can accept a Proposal and pay an invoice without seeing internal provider economics.

38.2 Client Collaborator

I can comment, upload inspiration and review shared Project information without accidentally making a formal commitment.
I can respond to meetings assigned to me.

38.3 Designer

I can publish a Project update once and know the client sees only approved content.
I can request a formal Decision instead of searching email for ambiguous approval.
I can understand which client action is blocking the Project.

38.4 Workspace owner

I can configure client branding, roles and notification templates while retaining platform safety.

38.5 Registry operator

I can investigate access or decision disputes through an auditable history without exposing unrelated Workspace information.

39. Acceptance Criteria

39.1 Identity and access

Each client participant signs in as an individual user.
Invitation preview shows Project and authority before sending.
Expired/revoked invitations cannot activate.
Access changes take effect server-side and revoke prohibited future reads.
Multi-Workspace users cannot cross context accidentally.

39.2 Dashboard and Projects

Dashboard prioritizes outstanding actions and next events.
Client Project data comes from canonical shared records.
Only published milestones, updates and files appear.
Seven-Phase progress maps to stable Phase IDs and supports overlap.
Empty states remain calm and useful.

39.3 Decisions

Every formal response references the exact Decision version reviewed.
Unauthorized or stale responses are rejected.
Comments cannot change approval state.
Changes requested create a linked revision workflow without mutating the prior version.
Multi-party policy produces deterministic results and conflict handling.
High-impact confirmation clearly states the action and records assurance/audit.

39.4 Presentations and selections

Published presentations are immutable versions.
Client comments link to the intended page/room/item.
Selection approval shows permitted financial impact.
Internal vendor source, cost and margin remain hidden.
Bulk approval is limited to an explicit versioned set.

39.5 Budget and commercial

Client totals reconcile to permitted canonical sources.
Hidden cost components cannot appear in API, export, notification or AI.
Proposal acceptance references an immutable commercial version.
Manual payment claims do not create settled state without reconciliation.
Financial capabilities are separate from document view access.

39.6 Calendar, communication and files

Clients see only explicitly shared appointments.
Confirmed appointment changes require client-visible reschedule flow.
Internal Notes never appear as client Messages.
Formal approval cannot be completed through a message reply.
Files use scoped access and preserve issued versions.
Client uploads remain pending/reviewed until intentionally published.

39.7 Delivery and installation

Client status does not expose other clients, hidden providers or private routing.
Changes and exceptions are published intentionally.
Completion/deficiency evidence is permission-filtered.

39.8 Notifications and AI

Every required event exists in the Notification Builder.
Deep links preserve intended destination after authentication.
SMS contains no unnecessary sensitive detail.
AI answers use only client-visible sources and cannot perform formal actions.

39.9 Security and reliability

Automated RLS tests prove client-to-client and Workspace isolation.
Search, realtime, files, exports, notifications and AI obey the same audience boundary.
High-risk mutations are idempotent and auditable.
Concurrent/stale Decision submissions cannot corrupt the governing outcome.

40. Test Matrix

40.1 Roles

Decision Maker, Collaborator and View Only on the same Project.
Financial authority separated from design approval.
Delegation starts/expires correctly.
Access removed during active session.

40.2 Decisions

single approver;
any authorized approver;
unanimous and minimum-count policy;
conflicting responses;
superseded version;
overdue and withdrawn Decision;
step-up authentication failure;
duplicate network submission.

40.3 Visibility

hidden provider identity;
internal note linked to visible Project;
client-visible item with hidden cost;
revoked file after notification;
search and AI prompt for hidden content;
export with masked fields.

40.4 Commercial

Proposal revised during review;
invoice viewed by non-payer;
payment webhook delayed/duplicated;
manual bank payment pending reconciliation;
refund and corrected receipt.

40.5 Mobile/accessibility

notification to login to intended action;
320-pixel approval flow;
screen-reader Decision review;
keyboard presentation navigation;
large-text/reflow;
interrupted upload.

41. Definition of Done

Client domain boundaries and canonical record ownership are implemented.
Every client-facing row has RLS and audience tests.
Dashboard, Project, Decision, Message, Calendar, File and Commercial surfaces reuse shared components.
Formal action/version history is immutable and auditable.
Client roles and field visibility have safe defaults.
Notification templates exist and have been rendered across channels.
Mobile and accessibility QA pass.
Migration reconciliation passes for pilot Projects.
Support and incident runbooks exist for access, approval and payment disputes.
Analytics are privacy-reviewed.
Feature flags and rollback are tested.

42. Final Product Direction

The Client Portal should make a complex design Project feel considered, transparent and effortless. The client should never need to understand the platform’s internal pipelines, provider network economics or operational database to make a confident decision. At the same time, the portal must not achieve simplicity by creating disconnected records or sacrificing governance.

The best experience is created when every participant works from the same underlying Project and the system reveals only what each participant needs. Designers publish curated progress and request clear Decisions. Clients review beautiful, versioned material and take explicit action. Providers continue operating through their assigned workflows. Commercial records remain exact. The result is a premium client experience and a reliable operational system built from the same reusable platform components.

Current-product review gap closure register

Generated: August 4, 2026
Owning future specification: 13
Mapped current-product profiles: 2
Recorded review gaps: 9

This register is part of the release contract. It maps the current-product reverse review into required future behavior. A gap is not closed because a screen exists; closure requires the corrected canonical data, permissions, states, migration, audit and test evidence described below.

Register rules

Every profile in the Current Product Library must resolve to one owning future specification.
Current limitations are evidence, not optional ideas. If a limitation is intentionally retained, the specification must record the decision, risk, owner and review date.
Shared-component defects are corrected through Spec 16 and then consumed here; feature teams may not create local replacement controls.
Permission, contact, financial and visibility defects also require Spec 08 enforcement, even when the functional feature is owned by another specification.
Legacy Proper Gallery, Lead, Partner and implementation-facing labels are migration inputs only and must not return through new UI, APIs, exports or notifications.
Verification must use realistic fixtures for Admin, Designer, Provider and Client audiences where applicable.

G01 — Clients directory

Current-product profile: clients-directory
Observed route: /admin/clients
Evidence confidence: Verified

Review gaps

No dedicated Client Profile exists.
Legacy Leads labels remain in metrics and columns.
Client rows expose phone, email and Pipeline value without a verified permission variant.
Rooms, Services Needed and Designer Specialties appear as single-select controls despite likely multi-value semantics.
Matching Profile percentage is unexplained.
Duplicate detection, merge, household/organization relationships and Portal status are absent.

Required future closure

Build dedicated Client Profile from Spec 13.
Replace Leads with Project Opportunities and canonical Pipeline Record links.
Add Overview, Project Opportunities, Projects, Matching, Decisions, Files, Tasks, Communication, Activity and History modules.
Correct multi-select fields through the shared field registry.
Add duplicate resolution, household/organization relationships and Client Portal access state.

Closure evidence required

The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
Automated tests cover the identified defect or missing journey so it cannot silently regress.
Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

G02 — Client Profile

Current-product profile: client-profile
Observed route: /admin/clients/:id
Evidence confidence: Known limitation