Project Timeline & Milestone Visualization Guide

Last Updated: 2026-01-17 Status: Implemented Plan Reference: 132-project-timeline-visualization.md

Overview

The Project Timeline feature provides visual timeline and milestone visualization for client portal users. Clients can see project phases, milestone progress, upcoming deadlines, and overall project timeline at a glance, eliminating the need to read through text-based lists.

Table of Contents

1. Accessing Timeline
2. Features
3. How to Use
4. Milestone Status Indicators
5. Deadline Indicators
6. Technical Architecture
7. Related Features

Accessing Timeline

Navigation

Permissions

Features

Visual Timeline

• Vertical list timeline with status indicators
• Progress bars for overall and milestone-level completion
• Clear date indicators for each milestone
• Visual connection line between milestones

Progress Tracking

• Overall project progress percentage
• Individual milestone progress
• Completed deliverables count

Deadline Visualization

• Days until due countdown
• Overdue warnings with pulsing indicators
• Due this week alerts

Interactive Elements

• Click milestone to view details
• Expand/collapse deliverables list
• Link to milestone acceptance page

How to Use

Viewing Project Timeline

1. Navigate to Portal → Projects → [Project]
2. Scroll to the Timeline section or click the Timeline tab
3. View milestones in chronological order
4. Check overall progress bar at the top

Understanding the Timeline

Progress Bar: The progress bar at the top shows overall project completion based on completed milestones:

[========Progress Bar 65%========]

Milestone List: Milestones are displayed vertically with:

• Status indicator (colored circle)
• Milestone name and due date
• Deliverables checklist
• Days remaining or overdue count

Interacting with Milestones

• Click milestone card to see full details
• Hover over deliverables for status info
• Click "View Details" to access milestone acceptance page

Milestone Status Indicators

Status Colors (Tailwind Classes)

<!-- Complete -->
<div class="bg-green-500">...</div>

<!-- In Progress -->
<div class="bg-blue-500">...</div>

<!-- Pending -->
<div class="bg-gray-300 dark:bg-gray-600">...</div>

<!-- Overdue -->
<div class="bg-red-500 animate-pulse">...</div>

Deadline Indicators

Deadline Badges

Example Display

✓ Discovery Phase - Jan 5 (Complete)
● Design Phase - Jan 15 (3 days left)
○ Development - Feb 1
○ Launch - Feb 28

Technical Architecture

Service

Location: app/Services/Portal/ProjectTimelineService.php

class ProjectTimelineService
{
    public function getTimeline(Project $project): ProjectTimeline
    {
        $milestones = $project->milestones()
            ->orderBy('due_date')
            ->get();

        return new ProjectTimeline(
            project: $project,
            milestones: $milestones->map(fn($m) => $this->formatMilestone($m)),
            startDate: $milestones->min('created_at'),
            endDate: $milestones->max('due_date'),
            overallProgress: $this->calculateProgress($milestones),
        );
    }
}

Data Transfer Object

Location: app/DataTransferObjects/ProjectTimeline.php

class ProjectTimeline
{
    public function __construct(
        public Project $project,
        public Collection $milestones,
        public ?Carbon $startDate,
        public ?Carbon $endDate,
        public int $overallProgress,
    ) {}
}

Milestone Data Structure

Each formatted milestone includes:

Components

Location: resources/views/components/portal/

Controller

Location: app/Http/Controllers/Portal/ProjectController.php

Routes

// In routes/portal.php
Route::get('/projects/{project}/timeline', [ProjectController::class, 'timeline'])
    ->name('portal.projects.timeline');

Route::get('/api/projects/{project}/timeline', [ProjectController::class, 'timelineData'])
    ->name('portal.api.projects.timeline');

Progress Calculation

Overall Progress

private function calculateProgress(Collection $milestones): int
{
    if ($milestones->isEmpty()) return 0;

    $completed = $milestones->where('status', 'completed')->count();
    return (int) round(($completed / $milestones->count()) * 100);
}

Milestone Progress

Individual milestone progress is based on:

• Deliverables completion percentage
• Or explicit progress_percentage field if set

Empty State

When a project has no milestones:

@if($timeline->milestones->isEmpty())
    <div class="text-center py-8 text-gray-500">
        <x-icon name="calendar" class="w-12 h-12 mx-auto mb-4" />
        <p>No milestones have been added to this project yet.</p>
    </div>
@endif

Mobile Responsiveness

The timeline is fully responsive:

• Vertical layout works well on all screen sizes
• Progress bars scale appropriately
• Milestone cards stack vertically
• Touch-friendly tap targets

Related Features

Dependencies

Complementary Features

Future Enhancements

• Drag-and-drop milestone reordering (admin)
• Critical path highlighting
• Dependency arrows between milestones
• Export timeline as PDF/image
• Calendar integration (add deadlines to calendar)
• Push notifications for approaching deadlines
• Historical timeline comparison
• Gantt chart view for larger projects

Troubleshooting

See Also

• Project Management - Project overview
• Milestone Acceptance - Deliverable approval
• Client Dashboard - Portal home