# Walkthrough — RC-018: Timeline Planner & Wedding Checklist

Implement the Wedding Planning Timeline & Checklist module inside the Couple Portal, providing automatically seeded phases, countdowns, progress gauges, calendar month grids, and milestones lists.

---

## 1. Architecture Overview
The Timeline Planner follows a modular MVC design under the `App\Modules\Timeline` namespace:

```mermaid
graph TD
    Router[couple.php Routes] -->|Require| TimelineRoutes[app/modules/Timeline/routes.php]
    TimelineRoutes -->|GET /app/couple/timeline| TimelineController[TimelineController.php]
    TimelineController -->|Seeding & Stats| TimelineModel[TimelineModel.php]
    TimelineModel -->|Read/Write| DB[(MariaDB Database)]
    TimelineController -->|Render| ViewDashboard[timeline/dashboard.php]
    TimelineController -->|Render| ViewTasks[timeline/tasks.php]
    TimelineController -->|Render| ViewCalendar[timeline/calendar.php]
    TimelineController -->|Render| ViewMilestones[timeline/milestones.php]
```

---

## 2. Database Schema Details
Three new tables were appended to [schema.sql](file:///c:/xampp/htdocs/inveetaire/database/schema.sql) and migrated to the active database instance:
- **`timeline_phases`**: Planning periods (e.g., '12+ Months', '1 Week', 'Wedding Day').
- **`timeline_tasks`**: Checklist actions joined with category, status, priority, due date, estimated duration, assignee, and reminder settings.
- **`timeline_milestones`**: Key checkpoints displaying on the dashboard.

---

## 3. MVC Component Logic

### Module Route Definitions
Registered in [routes.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Timeline/routes.php):
- `GET /app/couple/timeline`: Dashboard summary view.
- `GET/POST /app/couple/timeline/tasks/*`: Tasks checklist CRUD, pagination, and status toggles.
- `GET /app/couple/timeline/calendar`: Monthly grid calendar view.
- `GET/POST /app/couple/timeline/milestones/*`: Milestone CRUD and check completion toggles.

### Controller Actions
[TimelineController.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Timeline/TimelineController.php) processes filters, handles pagination, parses form posts, validates required fields, and flashes operations results.

### Model Engine
[TimelineModel.php](file:///c:/xampp/htdocs/inveetaire/app/modules/Timeline/TimelineModel.php) handles business calculations:
- **checklists Auto-Seeding**: Automatically seeds 10 default planning phases, 21 default tasks, and 4 major milestones. Due dates are calculated dynamically relative to the workspace's configured wedding date.
- **Progress Tracking**: Computes countdown days, overdue indicators, completed task counts, and completion percentage rings.
- **Calendar Days Matrix**: Aggregates scheduled tasks within their due date month cell blocks.

---

## 4. UI View Templates
Views are structured inside [app/views/timeline/](file:///c:/xampp/htdocs/inveetaire/app/views/timeline/):
- **`dashboard.php`**: Countdown banners, overall completion percentage gauges, upcoming due tasks this week, overdue item alerts, milestones checklist, and quick milestone adding.
- **`tasks.php`**: Checklist datatable with search, phase, category, and status filters.
- **`create_task.php` & `edit_task.php`**: Form panels with conditional Alpine.js alert toggles.
- **`calendar.php`**: Pure-PHP Month Calendar widget displaying due tasks directly on day cells.
- **`milestones.php`**: Milestone checkpoint settings page.

---

## 5. Verification Metrics & Tests
- **PHP Syntax Validation**: Verified that all backend files compile with no errors.
- **Model Functional Tests**: Seeding offsets, custom additions, status toggles, progress percentages, and milestones checked out successfully via the test runner script.
- **Browser Runtime Testing**: Verified dashboard layouts, navigation lists, calendar navigation, and checkbox toggling.

### Browser Walkthrough Screenshots:
![Timeline Dashboard](/C:/Users/FRIDAY/.gemini/antigravity-ide/brain/57840c77-f2bc-454f-9f01-9b09c72f508a/timeline_dashboard_1784113377082.png)
*Timeline Dashboard page showing progress rings, countdowns, and quick milestone forms.*

![Tasks Checklist](/C:/Users/FRIDAY/.gemini/antigravity-ide/brain/57840c77-f2bc-454f-9f01-9b09c72f508a/tasks_checklist_1784113389399.png)
*Wedding tasks checklist table with filter bars and action dropdown buttons.*

![Monthly Calendar Grid](/C:/Users/FRIDAY/.gemini/antigravity-ide/brain/57840c77-f2bc-454f-9f01-9b09c72f508a/timeline_calendar_1784113398804.png)
*Monthly calendar layout rendering task items inside scheduled cells.*