Client Portal — Complete Feature Decomposition¶

SCOPE_ITEM: Exhaustive feature tree for client portal applications. Each node is a scope item that can be independently included or excluded during scoping.

1. Authentication & Access¶

SCOPE_ITEM: Secure authentication for client users with strict data isolation per client organisation.

1.1 Client User Authentication¶

SCOPE_ITEM: Login flow for client-side users.

INCLUDES: - Magic link authentication (email, 15-minute expiry, single-use). - Email + password as alternative (bcrypt cost 12, minimum 12 chars). - Session management (JWT via NextAuth.js, 8-hour lifetime). - Password reset flow (if password auth enabled).

OPTIONAL: - SSO integration (client's corporate IdP via SAML/OIDC). - MFA (TOTP, mandatory for regulated portals). - Social login (Google — only if client's users use personal accounts).

CHECK: Magic link is the recommended default for client portals. Lower friction, no password management, sufficient security for most use cases. CHECK: If client's customers are enterprises with their own IdP, offer SSO integration as a premium feature.

1.2 Company Staff Authentication¶

SCOPE_ITEM: Login flow for the company's internal team.

INCLUDES: - Email + password with MFA (TOTP mandatory for admin users). - Role-based access: admin, project manager, team member, read-only. - Client context switching (admin selects which client to view).

OPTIONAL: - SSO via company's IdP (if company has Entra ID/Google Workspace). - Impersonation (view portal as specific client user — audit logged).

1.3 Client Organisation Management¶

SCOPE_ITEM: Multi-tenancy — each client is a separate tenant.

INCLUDES: - Client organisation record (name, logo, primary contact, address). - Client user management (invite, deactivate, role assignment). - Roles per client org: primary contact, team member, read-only. - Strict data isolation (all queries scoped by client_id).

OPTIONAL: - Client self-service user management (primary contact adds/removes). - Client branding (logo on portal, custom accent colour). - Client-specific feature flags (enable/disable modules per client).

1.4 Data Model¶

CREATE TABLE client_organisations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  logo_url TEXT,
  primary_contact_id UUID,
  address JSONB,
  settings JSONB DEFAULT '{}',  -- feature flags, branding
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  password_hash TEXT,                          -- null for magic-link only
  role TEXT NOT NULL,                           -- admin, staff, client_primary, client_member, client_readonly
  client_org_id UUID REFERENCES client_organisations(id),  -- null for company staff
  is_active BOOLEAN DEFAULT true,
  last_login_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT now()
);

2. Dashboard¶

SCOPE_ITEM: Client-facing overview of projects, KPIs, and status. See: dashboard.md

2.1 Client Dashboard¶

SCOPE_ITEM: Landing page after client login. INCLUDES: Active projects summary, recent activity feed, upcoming milestones/deadlines, unread messages indicator, outstanding invoices indicator. OPTIONAL: Customisable widget layout, KPI cards with trends, quick actions (upload document, send message, create ticket).

2.2 Project Status¶

SCOPE_ITEM: Per-project status overview. INCLUDES: Project name and description, current phase/status, milestone timeline (visual), completion percentage, key contacts (assigned team members). OPTIONAL: Gantt chart view, time tracking visibility, budget tracking (spent vs allocated), issue/risk register.

2.3 KPI Display¶

SCOPE_ITEM: Client-specific performance metrics. INCLUDES: KPI cards (numeric value + trend + comparison period). OPTIONAL: Chart widgets (line, bar, pie), KPI definitions configurable per client, KPI data entry by company staff.

2.4 Activity Feed¶

SCOPE_ITEM: Chronological log of recent actions. INCLUDES: New documents shared, project status updates, messages received, invoice created, milestone completed. OPTIONAL: Filtered view (by project, by type), mark as read.

3. Document Management¶

SCOPE_ITEM: Secure document sharing with versioning and access control. See: document-management.md

3.1 Document Upload¶

SCOPE_ITEM: Upload files to share with clients. INCLUDES: Drag-and-drop upload (presigned URL to S3), file type validation (configurable whitelist), virus scanning (ClamAV), max file size (100 MB default), progress indicator. OPTIONAL: Bulk upload, folder creation, zip file extraction.

3.2 Document Versioning¶

SCOPE_ITEM: Track revisions of shared documents. INCLUDES: Version history per document (v1, v2, v3...), download any version, current version indicator, version note (what changed), automatic version increment on re-upload. OPTIONAL: Visual diff for text documents (PDF compare), restore previous version, version comparison side-by-side.

3.3 E-Signatures¶

OPTIONAL: SCOPE_ITEM: Legally binding electronic signatures on documents. INCLUDES: Send document for signature (via ZealID, Signicat, or Scrive API preferred — EU-based. DocuSign or Dropbox Sign secondary if client explicitly requires — US-based, EU data sovereignty risk), signature status tracking (pending, signed, declined), signed document auto-stored in portal, audit trail. OPTIONAL: Multi-party signatures (sequential or parallel), signing order, reminder automation, template library.

3.4 Access Control¶

SCOPE_ITEM: Control who can see and download documents. INCLUDES: Documents scoped to client organisation (automatic), document visibility per project, download logging (who, when). OPTIONAL: Document-level permissions (specific users within client org), expiring access, view-only mode (watermarked, no download), NDA/confidentiality acknowledgement before first access.

3.5 Retention Policies¶

SCOPE_ITEM: Automated document lifecycle management. INCLUDES: Retention period per document type (configurable), warning notification before expiry, archived state (hidden but retained), permanent deletion after retention period. OPTIONAL: Legal hold (prevent deletion during disputes/audits), automated archival to cold storage.

3.6 Document Categories¶

SCOPE_ITEM: Organised document library. INCLUDES: Category assignment per document (contract, deliverable, invoice, correspondence, report), filter by category, category-based retention policies. OPTIONAL: Custom categories per client, tag-based organisation, full-text document search (PDF content indexing).

4. Communication¶

SCOPE_ITEM: Messaging, notifications, and support between company and client. See: communication.md

4.1 In-Portal Messaging¶

SCOPE_ITEM: Secure messaging between client and company team. INCLUDES: Conversation threads (per project or general), text messages with formatting, file attachments, read receipts, message history. OPTIONAL: @mention team members, message reactions, message search, pinned messages.

4.2 Notification Centre¶

SCOPE_ITEM: In-app notification hub. INCLUDES: Notification bell with unread count, notification list (new document, message, status change, invoice), click-to-navigate, mark as read / mark all as read. OPTIONAL: Notification preferences (per channel: in-app, email), notification digest (daily summary email).

4.3 Email Notifications¶

SCOPE_ITEM: Automated email alerts for portal events. INCLUDES: New document shared, new message received, project status changed, invoice created, milestone upcoming. Sent via: Brevo (FR) or Mailjet (FR) API preferred. Resend/Postmark secondary (US-based — EU data sovereignty risk). OPTIONAL: Reply-to-email creates portal message, email digest (daily/weekly summary), customisable email templates per client.

4.4 Support Ticket System¶

OPTIONAL: SCOPE_ITEM: Structured support request handling. INCLUDES: Ticket creation (subject, description, priority, category), ticket status workflow (open, in progress, waiting, resolved, closed), ticket assignment to company team member, internal notes (client cannot see), ticket history and resolution tracking. OPTIONAL: SLA tracking per ticket priority, canned responses, satisfaction rating after resolution, knowledge base / FAQ.

5. Invoicing & Payments¶

OPTIONAL: SCOPE_ITEM: Invoice presentation and optional online payment.

5.1 Invoice Display¶

SCOPE_ITEM: View invoices within the portal. INCLUDES: Invoice list (date, number, amount, status, due date), invoice detail view, PDF download, payment status indicator (unpaid, overdue, paid, partially paid). OPTIONAL: Invoice line item detail, filtering by status/date/project.

5.2 Online Payment¶

OPTIONAL: SCOPE_ITEM: Pay invoices directly through the portal. INCLUDES: Payment link per invoice (Mollie preferred — NL-based. Stripe secondary if client requires — US-based, EU data sovereignty risk), payment methods (iDEAL, credit card, bank transfer), automatic status update on payment confirmation, payment receipt email. OPTIONAL: Partial payment, recurring payment setup, auto-pay configuration.

5.3 Payment History¶

SCOPE_ITEM: View past payments. INCLUDES: Payment list (date, amount, invoice reference, method), payment receipt download. OPTIONAL: Export payment history (CSV), annual statement.

6. Reporting¶

OPTIONAL: SCOPE_ITEM: Reports generated by company, accessible to client.

6.1 Shared Reports¶

SCOPE_ITEM: Reports published to client via portal. INCLUDES: Report list per client (title, date, type), PDF report download, report notification on publish. OPTIONAL: Interactive report (embedded charts, date range filter), scheduled report delivery (monthly summary).

6.2 Data Export¶

SCOPE_ITEM: Client self-service data export. INCLUDES: Export project data (CSV), export document list (CSV). OPTIONAL: Export all client data (GDPR portability), API access for data extraction (advanced clients).

SCOPE_ITEM: Lightweight file exchange for large deliverables.

7.1 Client Upload¶

SCOPE_ITEM: Client can upload files to share with company. INCLUDES: Upload zone (drag-and-drop), file type validation, virus scanning, notification to company on upload. OPTIONAL: Upload request (company requests specific file from client), upload deadline with reminder.

7.2 Shared File Library¶

SCOPE_ITEM: Organised file repository per project. INCLUDES: File list with metadata (name, size, type, uploaded by, date), download individual files, file categorisation. OPTIONAL: File preview (images, PDF), bulk download (zip), file commenting.

8. Calendar & Scheduling¶

OPTIONAL: SCOPE_ITEM: Meeting scheduling and project timeline visibility.

8.1 Appointment Booking¶

OPTIONAL: SCOPE_ITEM: Client can book meetings with company team. INCLUDES: Available slot display (synced from team calendar), booking form (date, time, agenda), confirmation email, calendar invite (.ics) attachment. OPTIONAL: Video call link auto-generation (Google Meet, Teams, Zoom), rescheduling and cancellation, recurring meeting setup.

8.2 Project Timeline¶

OPTIONAL: SCOPE_ITEM: Visual project schedule accessible to client. INCLUDES: Milestone list with dates and status, timeline visualisation. OPTIONAL: Gantt chart view, dependency display, critical path highlighting.

9. Administration (Company Side)¶

SCOPE_ITEM: Back-office management for the company operating the portal.

9.1 Client Management¶

SCOPE_ITEM: Manage client organisations and their users. INCLUDES: Client list (name, status, projects, last active), client detail (users, projects, documents, invoices), client creation and deactivation. OPTIONAL: Client segmentation / tagging, client health score.

9.2 Project Management¶

SCOPE_ITEM: Manage projects visible in portal. INCLUDES: Project creation (name, client, team, milestones), project status updates (reflected in client dashboard), milestone management. OPTIONAL: Time tracking per project, budget tracking, resource allocation.

9.3 Content Management¶

SCOPE_ITEM: Manage portal content and announcements. INCLUDES: Announcement banner (shown to all or specific clients), FAQ/help content, portal terms of use. OPTIONAL: Knowledge base articles, video tutorials, getting-started guide for new clients.

9.4 Analytics¶

SCOPE_ITEM: Portal usage metrics. INCLUDES: Active clients (logged in last 30 days), document downloads, message volume, ticket volume. OPTIONAL: Per-client engagement metrics, feature usage tracking, client satisfaction trends.

Feature Inclusion Matrix¶

Feature	Services Portal	Project Portal	Account Mgmt	Regulated
1. Auth & Access	Required	Required	Required	Enhanced
2. Dashboard	Required	Required	Required	Required
3. Document Mgmt	Required	Required	Required	Enhanced
4. Communication	Required	Required	Required	Required
5. Invoicing	Optional	Optional	Required	Optional
6. Reporting	Optional	Optional	Required	Required
7. File Sharing	Required	Required	Optional	Required
8. Calendar	Optional	Optional	Optional	Excluded
9. Administration	Required	Required	Required	Enhanced