Client Collaboration Portal Guide

Last Updated: 2026-01-12 Status: Implemented Plan Reference: 036-client-collaboration-portal.md Enhancement Reference: 054-client-collaboration-enhancement.md, 090-client-collaboration-improvement.md

Overview

The Client Collaboration Portal transforms the client portal from a read-only view into an interactive collaboration platform. It provides document requests, deliverable approval workflows, progress tracking, milestone acceptance, file comments, and satisfaction surveys to enable seamless communication between administrators and clients.

Recent Enhancements (Plan 054)

• Document Request Templates: Create reusable templates for common document requests
• Multi-Stage Approval Workflows: Configure sequential or parallel approval stages with multiple approvers
• Enhanced Feedback System: File comments and project feedback now support types, status tracking, and priority levels
• Notification Preferences: Clients can configure their notification preferences for different collaboration events

Recent Enhancements (Plan 090)

• Unified CollaborationService: Centralized service for all collaboration features
• Collaboration Configuration: Configurable settings in config/client-collaboration.php
• Client/Project Summaries: Quick overview of collaboration status
• Pending Actions: Dashboard of pending collaboration items for users

Table of Contents

1. Accessing Collaboration Features
2. Document Requests
3. Document Request Templates
4. Deliverable Approvals
5. Multi-Stage Approval Workflows
6. File Comments & Feedback
7. Progress Tracking
8. Milestone Acceptance
9. Client Satisfaction Surveys
10. Client Uploads
11. Notification Preferences
12. Technical Architecture
13. Related Features

Accessing Collaboration Features

Client Portal Navigation

Admin Navigation

Permissions

Document Requests

Document requests allow administrators to request specific files or documents from clients.

Creating Requests (Admin)

1. Navigate to Admin → Document Requests
2. Click "Create Request"
3. Fill in request details:
   • Client: Select the client
   • Project (optional): Associate with a project
   • Title: Request title (e.g., "Tax Documents")
   • Description: Details about what's needed
   • Category: Contract, Invoice, Identity, Other
   • Required: Mark if mandatory
   • Due Date (optional): Set deadline
4. Click "Create Request"

Notification Flow

Admin creates request → Client notified → Client submits → Admin notified
                                       ↘ Admin approves/rejects → Client notified

Fulfilling Requests (Client)

1. Navigate to Portal → Document Requests
2. View pending requests
3. Click on a request to view details
4. Click "Submit Documents"
5. Upload required files (max 50MB each)
6. Add notes (optional)
7. Click "Submit"

Request Status

Viewing Submitted Documents (Admin)

1. Navigate to Admin → Document Requests
2. Click on a submitted request
3. View uploaded files
4. Download files to review
5. Click "Approve" or "Reject"
6. If rejecting, provide reason

Document Request Templates

Document request templates allow administrators to create reusable templates for common document requests, streamlining the request creation process.

Accessing Templates (Admin)

Navigate to Admin → Document Request Templates to manage templates.

Creating a Template

1. Navigate to Admin → Document Request Templates
2. Click "Create Template"
3. Fill in template details:
   • Template Name: Internal name (e.g., "Standard Logo Request")
   • Request Title: Default title for requests created from this template
   • Description: Default description explaining what's needed
   • Category: legal, financial, design, identity, project, other
   • Default Priority: low, normal, high, urgent
   • Default Due Days: Days until due (e.g., 7)
   • Accepted File Types: Restrict to specific types (pdf, doc, png, etc.)
4. Click "Create Template"

Template Categories

Using Templates

When creating a new document request:

1. Select a template from the dropdown
2. Template values auto-populate the form
3. Modify as needed for this specific request
4. Create the request

Template Management

• Toggle Status: Activate/deactivate templates
• Usage Count: Track how many times a template has been used
• Edit: Modify template settings
• Delete: Remove unused templates

Deliverable Approvals

The deliverable approval workflow allows clients to review and approve work deliverables.

Submitting Deliverables (Admin)

1. Navigate to Admin → Projects → [Project]
2. Click "Submit Deliverable"
3. Fill in submission details:
   • Title: Deliverable name
   • Description: What's included
   • File (optional): Attach project file
   • Milestone (optional): Link to milestone
4. Click "Submit for Approval"

Reviewing Deliverables (Client)

1. Navigate to Portal → Projects → [Project] → Deliverables
2. View pending deliverables
3. Click on a deliverable to review
4. Download and review attached files
5. Choose action:
   • Approve: Accept the deliverable
   • Request Revision: Ask for changes
   • Reject: Decline the deliverable
6. Add feedback (required for revisions/rejection)

Approval Status

Revision Workflow

Admin submits (v1) → Client requests revision → Admin resubmits (v2) → Client approves

Each resubmission increments the revision number.

Multi-Stage Approval Workflows

Multi-stage approval workflows enable complex approval processes with multiple stages and approvers, ideal for enterprise clients or regulated industries.

Accessing Workflows (Admin)

Navigate to Admin → Approval Workflows to manage workflows.

Creating a Workflow

1. Navigate to Admin → Approval Workflows
2. Click "Create Workflow"
3. Fill in workflow details:
   • Workflow Name: Descriptive name (e.g., "Design Review Process")
   • Description: When this workflow should be used
   • Sequential Stages: Whether stages must be completed in order
   • Require All Approvers: Default approval requirement per stage
4. Add Approval Stages:
   • Stage Name: Name for this stage (e.g., "Design Review")
   • Approvers: Select users who can approve this stage
   • Required Approvals: How many approvers must approve
5. Click "Create Workflow"

Workflow Types

Stage Configuration

Each stage can have:

• Multiple approvers
• Required approval count (e.g., 2 of 3 must approve)
• Automatic advancement when requirements met

Using Workflows with Deliverables

1. When submitting a deliverable, select an approval workflow
2. The deliverable starts at Stage 1
3. Designated approvers review and approve
4. When stage requirements are met, advances to next stage
5. After final stage, deliverable is marked as approved

Workflow Status Tracking

Progress Visualization

Stage 1 (Design Review)    Stage 2 (Final Approval)
    [✓] Completed       →      [●] In Progress
    Approved by: John          Waiting: Jane, Mike

Workflow Management

• Duplicate: Copy a workflow for modification
• Toggle Status: Activate/deactivate workflows
• View Details: See approvers and recent approvals
• Edit: Modify stages and approvers

File Comments & Feedback

Adding Comments to Files

1. Navigate to a project file
2. Click "Add Comment"
3. Select comment options:
   • Type: general, question, feedback, issue, suggestion
   • Priority (optional): low, normal, high, urgent
4. Enter your comment
5. Click "Post"

Comment Types

Comment Status

Comment Threading

• Comments support nested replies
• Click "Reply" on any comment to respond
• Thread maintains conversation context

Resolving Comments

1. Review the comment
2. Click "Mark Resolved"
3. Comment moves to resolved state
4. Resolution logged with user and timestamp

Comment Visibility

Project Feedback

Clients can provide general feedback on projects:

1. Navigate to Portal → Projects → [Project]
2. Click "Leave Feedback"
3. Select feedback options:
   • Type: general, milestone, deliverable, concern, praise
   • Priority: low, normal, high, urgent
4. Enter feedback text
5. Click "Submit"

Feedback Status Tracking

Progress Tracking

Viewing Progress (Client)

1. Navigate to Portal → Projects → [Project]
2. View progress bar showing completion percentage
3. Click "View History" to see updates

Updating Progress (Admin)

1. Navigate to Admin → Projects → [Project]
2. Click "Update Progress"
3. Set Percentage (0-100%)
4. Add Breakdown (optional):

   {
     "design": 100,
     "development": 75,
     "testing": 25
   }
   

5. Add Notes describing what changed
6. Click "Update"

Progress Components

The visual progress bar component shows:

• Overall percentage
• Phase breakdown (if provided)
• Last update timestamp
• Update history

Auto-Calculate from Milestones

Progress can be calculated automatically:

Progress % = (Completed Milestones / Total Milestones) × 100

Milestone Acceptance

Reviewing Milestones (Client)

1. Navigate to Portal → Projects → [Project]
2. View project milestones
3. Click on a completed milestone
4. Review milestone deliverables
5. Click "Accept Milestone" or "Reject"
6. Add acceptance comments (optional)
7. Sign if required (digital signature)

Acceptance Record

Each acceptance is recorded with:

• Accepting user
• Status (accepted/rejected)
• Comments
• Signature (if applicable)
• Timestamp

Milestone Status Flow

Pending → In Progress → Completed → Awaiting Acceptance → Accepted
                                                       ↘ Rejected

Client Satisfaction Surveys

Survey Types

Taking a Survey (Client)

1. Navigate to Portal → Surveys (or click email link)
2. Rate the following (1-5 stars):
   • Overall Satisfaction
   • Communication Quality
   • Work Quality
   • Timeliness
   • Value for Money
3. Provide feedback:
   • What went well
   • What could improve
4. Answer: Would you recommend? (Yes/No)
5. Click "Submit Survey"

Viewing Analytics (Admin)

1. Navigate to Admin → Satisfaction
2. View dashboard metrics:
   • Overall Score: Average rating
   • NPS Score: Net Promoter Score
   • Category Scores: By dimension
   • Trends: Over time
3. Filter by:
   • Date range
   • Client
   • Project

NPS Calculation

NPS = (% Promoters - % Detractors) × 100

Promoters: Rating 4-5
Detractors: Rating 1-2
Passives: Rating 3

Client Uploads

Uploading Files (Client)

1. Navigate to Portal → Uploads
2. Click "Upload File"
3. Select file(s) to upload
4. Fill in details:
   • Description: What the file contains
   • Category: Categorize the upload
   • Project (optional): Associate with project
5. Click "Upload"

File Limits

• Maximum file size: 50MB
• Supported types: Documents, images, archives

Managing Uploads

Clients can:

• View all their uploads
• Filter by category/project
• Download uploaded files
• Delete their own uploads

Notification Preferences

Clients can configure their notification preferences to control how they receive collaboration updates.

Accessing Preferences (Client)

Navigate to Portal → Settings → Notifications to manage preferences.

Configurable Events

Notification Channels

Reminder Frequency

Setting Preferences

1. Navigate to Portal → Settings → Notifications
2. For each event type, toggle:
   • Email: Receive email notifications
   • In-App: Receive in-app notifications
3. Set Reminder Frequency: How often to receive digests
4. Click "Save Preferences"

Default Preferences

New users receive these defaults:

• Document requests: Email + In-App
• Feedback received: Email + In-App
• Approval needed: Email + In-App
• Deliverable status: In-App only
• Reminder frequency: Normal

Reset to Defaults

Click "Reset to Defaults" to restore original notification settings.

Technical Architecture

Models

Location: app/Models/

Enums

Location: app/Enums/

// DocumentRequestStatus
enum DocumentRequestStatus: string {
    case Pending = 'pending';
    case Submitted = 'submitted';
    case Approved = 'approved';
    case Rejected = 'rejected';
}

// ApprovalStatus
enum ApprovalStatus: string {
    case Pending = 'pending';
    case Approved = 'approved';
    case Rejected = 'rejected';
    case RevisionRequested = 'revision_requested';
}

Services

Location: app/Services/Collaboration/

// DocumentRequestService
class DocumentRequestService
{
    public function create(array $data, User $requester): DocumentRequest;
    public function submit(DocumentRequest $request, array $files, User $user): void;
    public function approve(DocumentRequest $request, User $reviewer): void;
    public function reject(DocumentRequest $request, string $reason, User $reviewer): void;
    public function getOverdueRequests(): Collection;
}

// DeliverableService
class DeliverableService
{
    public function submit(Project $project, array $data, User $submitter): DeliverableApproval;
    public function approve(DeliverableApproval $approval, User $reviewer, ?string $feedback): void;
    public function reject(DeliverableApproval $approval, User $reviewer, string $feedback): void;
    public function requestRevision(DeliverableApproval $approval, User $reviewer, string $feedback): void;
}

// ProgressTrackingService
class ProgressTrackingService
{
    public function updateProgress(Project $project, int $percentage, ?array $breakdown, ?string $notes, User $user): ProjectProgress;
    public function calculateFromMilestones(Project $project): int;
    public function getProgressHistory(Project $project): Collection;
}

// SatisfactionService
class SatisfactionService
{
    public function recordSurvey(array $data, User $user): SatisfactionSurvey;
    public function getClientSatisfactionScore(Client $client): float;
    public function getProjectSatisfactionScore(Project $project): float;
    public function getAverageSatisfaction(): array;
}

// CollaborationNotificationService
class CollaborationNotificationService
{
    public function notifyDocumentRequest(DocumentRequest $request): void;
    public function notifyDeliverableSubmitted(DeliverableApproval $approval): void;
    public function notifyFeedbackReceived(ProjectFeedback $feedback): void;
    public function notifyApprovalNeeded(DeliverableApproval $approval): void;
    public function shouldNotify(User $user, string $type, string $channel): bool;
}

// CollaborationService - Unified API
class CollaborationService
{
    public function getClientSummary(Client $client): array;
    public function getProjectSummary(Project $project): array;
    public function createDocumentRequest(array $data, User $requestedBy): DocumentRequest;
    public function startConversation(array $data, User $createdBy): Conversation;
    public function sendMessage(Conversation $conversation, string $body, User $user): Message;
    public function submitFeedback(Project $project, array $data, User $user): ProjectFeedback;
    public function getPendingActions(User $user): array;
}

Controllers

Portal Controllers: app/Http/Controllers/Portal/

• DocumentRequestController
• DeliverableApprovalController
• ClientUploadController
• MilestoneAcceptanceController
• ProjectFeedbackController
• SurveyController
• NotificationPreferenceController

Admin Controllers: app/Http/Controllers/Admin/

• DocumentRequestController
• DocumentRequestTemplateController
• ApprovalWorkflowController
• DeliverableApprovalController
• FileCommentController
• ProjectProgressController
• SatisfactionController

Routes

// Portal routes
Route::prefix('portal')->middleware(['auth', 'client'])->group(function () {
    // Document Requests
    Route::get('document-requests', [DocumentRequestController::class, 'index']);
    Route::get('document-requests/{documentRequest}', [DocumentRequestController::class, 'show']);
    Route::post('document-requests/{documentRequest}/submit', [DocumentRequestController::class, 'submit']);

    // Deliverables
    Route::get('projects/{project}/deliverables', [DeliverableController::class, 'index']);
    Route::get('deliverables/{approval}', [DeliverableController::class, 'show']);
    Route::post('deliverables/{approval}/approve', [DeliverableController::class, 'approve']);
    Route::post('deliverables/{approval}/reject', [DeliverableController::class, 'reject']);
    Route::post('deliverables/{approval}/revision', [DeliverableController::class, 'requestRevision']);

    // File Comments
    Route::post('files/{projectFile}/comments', [FileCommentController::class, 'store']);
    Route::post('comments/{comment}/resolve', [FileCommentController::class, 'resolve']);

    // Progress & Surveys
    Route::get('projects/{project}/progress', [ProgressController::class, 'show']);
    Route::get('surveys/create', [SurveyController::class, 'create']);
    Route::post('surveys', [SurveyController::class, 'store']);

    // Uploads
    Route::get('uploads', [ClientUploadController::class, 'index']);
    Route::post('uploads', [ClientUploadController::class, 'store']);

    // Notification Preferences
    Route::prefix('settings')->group(function () {
        Route::get('notifications', [NotificationPreferenceController::class, 'edit']);
        Route::put('notifications', [NotificationPreferenceController::class, 'update']);
        Route::post('notifications/reset', [NotificationPreferenceController::class, 'reset']);
    });
});

// Admin routes
Route::prefix('admin')->middleware(['auth', 'admin'])->group(function () {
    Route::resource('document-requests', Admin\DocumentRequestController::class);
    Route::post('document-requests/{documentRequest}/approve', [Admin\DocumentRequestController::class, 'approve']);
    Route::post('document-requests/{documentRequest}/reject', [Admin\DocumentRequestController::class, 'reject']);

    // Document Request Templates
    Route::resource('document-request-templates', Admin\DocumentRequestTemplateController::class);
    Route::patch('document-request-templates/{template}/toggle', [Admin\DocumentRequestTemplateController::class, 'toggle']);

    // Approval Workflows
    Route::resource('approval-workflows', Admin\ApprovalWorkflowController::class);
    Route::patch('approval-workflows/{workflow}/toggle', [Admin\ApprovalWorkflowController::class, 'toggle']);
    Route::post('approval-workflows/{workflow}/duplicate', [Admin\ApprovalWorkflowController::class, 'duplicate']);

    Route::post('projects/{project}/deliverables', [Admin\DeliverableController::class, 'store']);
    Route::post('projects/{project}/progress', [Admin\ProgressController::class, 'update']);
    Route::get('satisfaction', [Admin\SatisfactionController::class, 'index']);
});

Notifications

Configuration

Location: config/client-collaboration.php

return [
    'document_requests' => [
        'enabled' => true,
        'max_files_per_request' => 10,
        'max_file_size_mb' => 50,
        'default_due_days' => 7,
        'allowed_file_types' => ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'png', 'jpg', 'jpeg', 'gif', 'zip'],
        'categories' => ['general', 'financial', 'legal', 'identity', 'other'],
        'priorities' => ['low', 'normal', 'high', 'urgent'],
        'auto_approve' => false,
        'notify_on_submit' => true,
    ],
    'messaging' => [
        'enabled' => true,
        'max_message_length' => 5000,
        'allow_attachments' => true,
        'max_attachments_per_message' => 5,
        'project_conversations' => true,
        'general_conversations' => true,
    ],
    'feedback' => [
        'enabled' => true,
        'types' => ['general', 'concern', 'suggestion', 'praise'],
        'visibility_options' => ['all', 'admin'],
        'require_project' => true,
        'allow_anonymous' => false,
    ],
    'approvals' => [
        'enabled' => true,
        'require_notes_on_reject' => true,
        'auto_approve_timeout_days' => null,
    ],
    'notifications' => [
        'email' => true,
        'in_app' => true,
        'digest' => false,
        'digest_frequency' => 'daily',
    ],
];

Blade Components

{{-- Progress Bar Component --}}
<x-progress-bar :percentage="$project->progress_percentage" :breakdown="$progress->breakdown" />

{{-- Comment Thread Component --}}
<x-comment-thread :comments="$file->comments" :file-id="$file->id" />

Best Practices

For Document Requests

1. Be specific about what documents are needed
2. Set reasonable due dates to give clients time
3. Review submissions promptly to maintain engagement
4. Provide clear rejection reasons so clients can fix issues

For Deliverable Approvals

1. Include detailed descriptions of what's being delivered
2. Attach relevant files for review
3. Respond to revisions quickly to keep projects moving
4. Provide constructive feedback when requesting changes

For Progress Updates

1. Update regularly (at least weekly for active projects)
2. Use breakdown for complex projects
3. Add notes explaining what was accomplished
4. Set realistic percentages to maintain trust

For Surveys

1. Send promptly after project completion
2. Keep surveys short for better completion rates
3. Review feedback and act on improvement suggestions
4. Share positive feedback with the team

Troubleshooting

Related Features

Dependencies

Complementary Features

See Also

• Project Management - Project workflows
• File Sharing - File management
• Notifications - Alert system
• Client Dashboard - Portal interface