Client Intake & Portal Flow Guide

Last Updated: 2026-01-17 Status: Implemented Plan Reference: 117-client-intake-portal-flow.md, 129-discovery-flow-email-notifications.md, 130-lead-scoring-automated-qualification.md

Overview

The Client Intake & Portal Flow transforms the portal from a project-centric view to a stage-based experience that guides clients from first contact through ongoing engagement. It implements a complete lead management pipeline with discovery questionnaires, call booking, and progressive feature disclosure based on client lifecycle stage.

Table of Contents

1. Client Lifecycle Stages
2. Accessing the Features
3. Client Discovery Flow
4. Admin Lead Management
5. Lead Scoring & Automated Qualification
6. Call Booking System
7. Stage-Based Portal Visibility
8. Technical Architecture
9. Workflow Integration
10. Related Features

Client Lifecycle Stages

Clients progress through a defined set of stages from initial sign-up to active engagement:

Stage Categories

• Discovery Phase: Prospect through Proposal Sent (pre-active clients)
• Active Phase: Proposal Accepted through Support (engaged clients)
• Lead Stages: All pre-Proposal Accepted stages

Accessing the Features

Portal Navigation (Clients)

Admin Navigation

Client Discovery Flow

Step 1: Sign Up & Questionnaire

When a new user signs up, they are associated with a client in the prospect stage. Upon accessing the portal, they are redirected to the discovery flow.

1. Client accesses portal
2. System creates discovery questionnaire
3. Client stage advances to questionnaire_pending
4. Client fills out 10-question discovery form

Questionnaire Questions

Auto-Save Functionality

The questionnaire supports automatic progress saving via AJAX:

// Auto-saves every 30 seconds and on field blur
POST /discovery/questionnaire/save
{
    "responses": {
        "project_description": "...",
        "project_type": "new_project",
        ...
    }
}

Step 2: Questionnaire Submission

1. Client submits completed questionnaire
2. Validation ensures required fields are filled
3. Client stage advances to questionnaire_submitted
4. Budget, timeline, and source are copied to client record
5. Workflow triggers send admin notifications

Step 3: Admin Review & Qualification

1. Admin reviews questionnaire in lead management
2. Admin qualifies or declines the lead
3. If qualified: Client stage → qualified
4. Client receives notification with call booking link

Step 4: Call Booking

1. Qualified client accesses call booking page
2. System shows available slots from admin availability
3. Client selects a time slot
4. Discovery call is created and scheduled
5. Client stage advances to discovery_scheduled

Step 5: Discovery Call & Proposal

1. Admin conducts discovery call
2. Admin marks call as completed with outcome
3. Client stage advances to discovery_completed
4. Admin prepares and sends proposal
5. Client stage → proposal_sent

Step 6: Activation

1. Client accepts proposal (signs agreement)
2. Client stage advances to proposal_accepted
3. Full portal access is granted
4. Project creation begins

Admin Lead Management

Lead List View

The lead list provides filtering and search capabilities:

Filters:

• Stage (tabs for each lead stage)
• Search (by name or company)
• Source (how they found us)

Sort Options:

• Created date
• Name
• Stage
• Stage changed date

Pipeline/Kanban View

Visual representation of leads across stages with drag-and-drop functionality:

┌─────────────┬───────────────────┬───────────────────┬───────────────┐
│  Prospect   │ Quest. Pending    │ Quest. Submitted  │  Qualified    │
├─────────────┼───────────────────┼───────────────────┼───────────────┤
│ [Lead Card] │ [Lead Card]       │ [Lead Card]       │ [Lead Card]   │
│ [Lead Card] │                   │ [Lead Card]       │               │
└─────────────┴───────────────────┴───────────────────┴───────────────┘

Lead Detail View

Shows complete lead information:

• Client profile and contact info
• Questionnaire responses (collapsible)
• Stage timeline
• Available stage transitions
• Action buttons (Qualify, Decline, Advance)
• Discovery call history

Actions

Lead Scoring & Automated Qualification

Overview

The lead scoring system automatically evaluates questionnaire responses and assigns a score from 0-100. Based on configurable thresholds, leads can be automatically qualified or declined, streamlining the lead review process.

Score Components

The score is calculated from 6 weighted components:

Total weights must equal 100.

Score Thresholds

Admin Settings

Access: Admin → Settings → Lead Scoring

The settings page allows admins to:

• Adjust qualification thresholds (auto-qualify, auto-decline)
• Enable/disable auto-qualify and auto-decline
• Modify component weights (must sum to 100)
• View a visual score range diagram
• Reset to defaults

Scoring on Submission

When a questionnaire is submitted:

1. QuestionnaireService::submit() is called
2. LeadScoringService::scoreAndSave() calculates and stores the score
3. Score, breakdown, and recommendation are saved to the questionnaire
4. If auto-qualify/decline is enabled:
   • Score ≥ threshold: Client stage → qualified
   • Score < threshold: Client stage → declined

Manual Rescoring

Admins can rescore any submitted questionnaire:

• From lead detail page: Click "Rescore" button
• Useful after changing scoring weights
• New score replaces old score

Score Display

Scores are displayed in multiple locations:

Score Color Coding

Database Schema

lead_scoring_settings table:

discovery_questionnaires table additions:

Services

Data Transfer Object

App\DataTransferObjects\LeadScore

Properties:
- total: int (0-100)
- breakdown: array (component scores)
- recommendation: string (auto_qualify|manual_review|auto_decline)

Methods:
- getColorClass(): string - Tailwind classes for display
- getRecommendationLabel(): string - Human-readable recommendation
- toArray(): array - Array representation

Seeder

# Seed default settings
php artisan db:seed --class=LeadScoringSettingsSeeder

Default settings:

• Auto-qualify threshold: 70
• Auto-decline threshold: 40
• Both auto-actions enabled
• Weights: Budget 30, Timeline 20, Project Type 15, Success Criteria 15, Company Info 10, Description 10

Call Booking System

Admin Availability Settings

Admins configure their weekly availability:

// Default availability: 9am-5pm weekdays
$availabilityService->setAvailability($admin, [
    ['day_of_week' => 1, 'start_time' => '09:00', 'end_time' => '17:00'], // Monday
    ['day_of_week' => 2, 'start_time' => '09:00', 'end_time' => '17:00'], // Tuesday
    // ...
]);

Configuration Options:

• day_of_week: 0 (Sunday) through 6 (Saturday)
• start_time / end_time: Time range
• slot_duration: Meeting length (default: 45 minutes)
• buffer_before / buffer_after: Buffer time (default: 15 minutes)
• is_active: Enable/disable day

Client Booking Interface

Clients see a calendar UI with available slots:

┌─────────────────────────────────────────────────────┐
│ January 2026                                         │
├─────┬─────┬─────┬─────┬─────┬─────┬─────┤
│ Sun │ Mon │ Tue │ Wed │ Thu │ Fri │ Sat │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│     │  5  │  6  │  7  │  8  │  9  │ 10  │
│     │ ●●● │ ●●● │ ●●● │ ●●● │ ●●● │     │
└─────┴─────┴─────┴─────┴─────┴─────┴─────┘

● = Available slot (click to expand times)

Slot Generation

The AvailabilityService generates available slots considering:

• Admin's weekly availability settings
• Existing booked meetings
• Buffer times before/after meetings
• Past slots (not shown)
• Today's remaining slots (adjusted for current time)

// Get slots for next 2 weeks
$slots = $availabilityService->getAvailableSlots(
    $admin,
    now()->addDay(),
    now()->addWeeks(2),
    45 // duration in minutes
);

Meeting Outcomes

After a discovery call, admins record outcomes:

Stage-Based Portal Visibility

Navigation Configuration

Portal navigation items are filtered based on client stage using visible_stages or hidden_stages in config/navigation.php:

// Only show during discovery phases
[
    'route' => 'portal.discovery.index',
    'label' => 'Discovery',
    'visible_stages' => [
        'prospect',
        'questionnaire_pending',
        'questionnaire_submitted',
        'qualified',
        'discovery_scheduled',
        'discovery_completed',
        'proposal_sent',
    ],
],

// Only show during active phases
[
    'route' => 'portal.projects.index',
    'label' => 'Projects',
    'visible_stages' => [
        'proposal_accepted',
        'active',
        'completed',
        'support',
    ],
],

Visibility Matrix

Dashboard Redirect

The PortalDashboardController redirects discovery-phase clients to the discovery hub:

public function index(Request $request): View|RedirectResponse
{
    $client = $request->user()->clients()->first();

    // Discovery clients go to discovery flow
    if ($client->isInDiscoveryPhase()) {
        return redirect()->route('portal.discovery.index');
    }

    // Active clients see full dashboard
    return view('portal.dashboard', [...]);
}

Technical Architecture

Models

Services

Controllers

Database Schema

clients table additions:

discovery_questionnaires table:

questionnaire_responses table:

discovery_calls table:

availability_slots table:

Views

Routes

Portal Discovery Routes (routes/portal-routes.php):

Route::prefix('discovery')->name('discovery.')->group(function () {
    Route::get('/', [DiscoveryController::class, 'index'])->name('index');
    Route::get('/questionnaire', [DiscoveryController::class, 'questionnaire'])->name('questionnaire');
    Route::post('/questionnaire/save', [DiscoveryController::class, 'saveProgress'])->name('save-progress');
    Route::post('/questionnaire/submit', [DiscoveryController::class, 'submit'])->name('submit');
    Route::get('/status', [DiscoveryController::class, 'status'])->name('status');
    Route::get('/book-call', [DiscoveryController::class, 'bookCall'])->name('book-call');
    Route::post('/book-call', [DiscoveryController::class, 'confirmBooking'])->name('confirm-booking');
    Route::get('/available-slots', [DiscoveryController::class, 'getAvailableSlots'])->name('available-slots');
});

Admin Lead Routes (routes/admin/leads.php):

Route::prefix('leads')->name('leads.')->group(function () {
    Route::get('/', [LeadController::class, 'index'])->name('index');
    Route::get('/pipeline', [LeadController::class, 'pipeline'])->name('pipeline');
    Route::get('/{client}', [LeadController::class, 'show'])->name('show');
    Route::get('/{client}/questionnaire', [LeadController::class, 'questionnaire'])->name('questionnaire');
    Route::post('/{client}/qualify', [LeadController::class, 'qualify'])->name('qualify');
    Route::post('/{client}/decline', [LeadController::class, 'decline'])->name('decline');
    Route::post('/{client}/advance-stage', [LeadController::class, 'advanceStage'])->name('advance-stage');
    Route::post('/{client}/update-pipeline', [LeadController::class, 'updatePipelinePosition'])->name('update-pipeline');
});

Automated Email Notifications

The discovery flow includes automated email notifications at every stage transition to keep prospects informed and engaged.

Email Notification Templates

Implementation Architecture

The email notifications use a hybrid approach:

1. Workflows (7 immediate notifications):

   • Triggered by model_updated or client_stage_changed events
   • Use the send_template_email action
   • Configurable via Admin → Workflows

2. Scheduled Command (2 time-based reminders):

   • Command: php artisan discovery:send-call-reminders
   • Runs every 15 minutes via scheduler
   • Sends 24h reminders (calls 23-25 hours away)
   • Sends 1h reminders (calls 30-90 minutes away)

Discovery Workflows

Reminder Tracking

The discovery_calls table tracks reminder status:

This prevents duplicate reminders when the command runs multiple times.

Seeding Templates and Workflows

# Seed notification templates (9 templates)
php artisan db:seed --class=DiscoveryNotificationTemplatesSeeder

# Seed workflows (7 workflows)
php artisan db:seed --class=DiscoveryWorkflowsSeeder

Testing Reminders

# Preview what reminders would be sent
php artisan discovery:send-call-reminders --dry-run

# Send reminders now
php artisan discovery:send-call-reminders

Email Template Variables

Templates support these variables:

Workflow Integration

The client intake flow integrates with the workflow automation system to trigger notifications and actions at key stage changes.

Registered Triggers

Trigger Configuration

model_updated triggers use conditions to filter events:

// WorkflowCondition for questionnaire submission
[
    'field' => 'status',
    'operator' => 'changed_to',
    'value' => 'submitted',
]

client_stage_changed triggers use trigger_config for stage filtering:

// Workflow trigger_config for qualified stage
[
    'trigger_type' => 'client_stage_changed',
    'trigger_config' => ['stage' => 'qualified'],
]

Usage Example

// Stage changes trigger workflows automatically via ClientStageService
$stageService->advanceStage($client, ClientStage::Qualified, [
    'changed_by' => auth()->id(),
    'notes' => 'Great fit for enterprise plan',
]);
// This fires the 'client_stage_changed' trigger with stage='qualified'

Best Practices

For Administrators

1. Review questionnaires promptly - Clients expect timely responses
2. Use qualification notes - Document why a lead was qualified/declined
3. Keep availability current - Update slots when schedule changes
4. Record call outcomes - Helps with pipeline analysis
5. Use the pipeline view - Visual overview of lead flow

For Developers

1. Use ClientStageService - Always use the service for stage changes to trigger workflows
2. Check stage access - Use $client->canAccessFeature() or stage methods
3. Handle transitions gracefully - Invalid transitions throw InvalidArgumentException
4. Leverage scopes - Models have scopes like leads(), active() for filtering

Code Examples

Changing a client's stage:

use App\Services\ClientStageService;
use App\Enums\ClientStage;

$stageService = app(ClientStageService::class);

// This validates the transition and triggers workflows
$stageService->advanceStage($client, ClientStage::Qualified, [
    'changed_by' => auth()->id(),
    'notes' => 'Great potential fit',
]);

Checking stage permissions:

// Using enum methods
if ($client->stage->canBookCall()) {
    // Show booking UI
}

if ($client->stage->isDiscoveryPhase()) {
    // Redirect to discovery
}

// Using service
$stageService = app(ClientStageService::class);
if ($stageService->canAccessFeature($client, 'projects')) {
    // Show projects
}

Getting available transitions:

$validNextStages = $client->stage->validTransitions();
// Returns array of ClientStage enums

Troubleshooting

Related Features

Dependencies

Complementary Features

See Also

• Client Management - Managing client records
• Workflow Automation - Automated actions
• Notifications - Email and in-app notifications
• Portal UI - Portal navigation patterns