# Pilot Analytics Dashboard - Development Roadmap

**Project Duration:** ~4-5 weeks (25-30 working days)  
**Start Date:** April 28, 2026  
**Target Delivery:** Late May 2026  

## Source Files

This roadmap is derived from the following source files:

- Primary: `Pilot_Dashboard_PO_Brief_v1.md` (v1.5)
- Primary: `Pilot_Dashboard_Requirements_v1.md` (v1.5)
- Supporting: `plan-pilotAnalyticsDashboard.prompt.md`
- Supporting: `Pilot-Dashboard-UI-UX-Design-Specification.md`
- Supporting visual reference: `Sample Pilot Dashboard.png` and the PyQt mockup

When source documents conflict, the v1.5 PO brief and v1.5 technical requirements take precedence.

---

## Roadmap Overview

This roadmap is divided into 4 phases with specific deliverables and time estimates. Each phase culminates in a PR-ready checkpoint.

### Phase Breakdown
- **Phase 1 (Foundation):** 5-6 days
- **Phase 2 (Core UI):** 7-8 days
- **Phase 3 (Analytics & Polish):** 6-8 days
- **Phase 4 (QA & Release):** 4-5 days

**Total:** 22-27 working days (frontend only)

---

## Phase 1: Foundation & Contracts (5-6 Days)

### Deliverables
- Extended job statuses (COMPLETED, INVOICED)
- Dashboard data models and API service layer
- Role-based home branching
- Backend endpoint specification document
- Dev environment with mock data setup

### Tasks

| Task | Owner | Days | Dependencies | Notes |
|------|-------|------|--------------|-------|
| **1.1** Extend JobStatus enum + global constants | Frontend | 1.0 | None | Update global.ts, JobStatuses map, status pipes |
| **1.2** Design dashboard data contracts (TypeScript interfaces) | Frontend | 1.0 | None | Define KPI, Summary, Operations, ActiveJobs, Trend, Performance models |
| **1.3** Implement dashboard service with 5 endpoints | Frontend | 1.5 | 1.2 | GET /api/dashboard/pilot/[kpi, summary, active-jobs, trend, performance] |
| **1.4** Add service unit tests with mock data | Frontend | 0.75 | 1.3 | Jasmine tests for service methods; mock HttpClient |
| **1.5** Update dashboard component role branching | Frontend | 0.75 | 1.1 | Inject AuthService, template *ngIf branching |
| **1.6** Backend spec: finalize 5 endpoints (NO implementation) | Backend/Frontend | 1.0 | 1.2 | Document request/response contracts; ready for backend sprint |
| **1.7** Setup mock data provider for dev | Frontend | 0.5 | 1.2 | Mock service for UI development without backend |

**Phase 1 Checkpoint:** PR ready, all constants aligned, service contracts finalized, no backend dependency blocking UI work.

**Commit Messages:**
```
refactor(global): add completed and invoiced job statuses
feat(dashboard): add pilot dashboard api service and response models
feat(home): add pilot-only dashboard branch with fallback disclaimer
docs(dashboard): specify pilot dashboard backend api contracts
```

---

## Phase 2: Core UI Delivery (7-8 Days)

### Deliverables
- Responsive 2-column layout
- KPI cards, daily summary, operations panels
- Active jobs list with status coloring and progress bars
- All core sections visually complete and clickable

### Tasks

| Task | Owner | Days | Dependencies | Notes |
|------|-------|------|--------------|-------|
| **2.1** Build responsive grid layout (65/35 split) | Frontend | 1.5 | 1.5 | PrimeNG p-grid, mobile stack order |
| **2.2** Create KPI card component + template | Frontend | 1.0 | 1.1 | Icons, historical sub-lines, responsive cards |
| **2.3** Implement daily summary strip (today vs yesterday) | Frontend | 0.75 | 1.1 | Trend arrows, percent deltas, green/red coloring |
| **2.4** Add operations today panel (distance + spray volume) | Frontend | 0.5 | 1.1 | 2-metric strip below summary |
| **2.5** Build active jobs list panel | Frontend | 2.0 | 1.1 | Status badges, left color bar, progress bars, row click → job detail |
| **2.6** Implement job row status colors (NEW=Blue, IN PROGRESS=Yellow, COMPLETED=Green) | Frontend | 0.75 | 2.5 | IN PROGRESS groups READY, DOWNLOADED, SPRAYED |
| **2.7** Add scroll behavior to active jobs panel | Frontend | 0.5 | 2.5 | Independently scrollable; handles 10+ jobs |
| **2.8** Unit + integration tests for layout (responsive, mobile) | Frontend | 0.5 | 2.1-2.7 | Karma tests, viewport mocking |
| **2.9** Accessibility audit (ARIA, keyboard nav, contrast) | Frontend | 0.5 | 2.1-2.7 | Lighthouse, manual review |

**Phase 2 Checkpoint:** Left column fully functional, responsive on mobile/tablet, all clicks wired to mock data.

**Commit Messages:**
```
feat(dashboard-ui): add responsive pilot dashboard layout shell
feat(dashboard-kpi): implement kpi cards daily summary and operations strip
feat(active-jobs): implement status-driven list with progress and navigation
test(dashboard-layout): add responsive and accessibility tests
```

---

## Phase 3: Analytics & Polish (6-8 Days)

### Deliverables
- Trend charts (hours flown, hectares per day)
- Performance indicators (XT Error, Altitude)
- Date range controls
- i18n for EN, PT, ES
- Error and loading states

### Tasks

| Task | Owner | Days | Dependencies | Notes |
|------|-------|------|--------------|-------|
| **3.1** Integrate p-chart for hours flown (line chart) | Frontend | 1.0 | 1.1 | Chart.js 2.9.3, PrimeNG wrapper |
| **3.2** Integrate p-chart for hectares per day (bar chart) | Frontend | 1.0 | 1.1 | Similar setup; add target line overlay |
| **3.3** Build date range control (calendar picker) | Frontend | 1.0 | 3.1-3.2 | Default current week Mon-Sun; user can change |
| **3.4** Implement XT Error indicator with thresholds | Frontend | 0.75 | 1.1 | Green <1m, Yellow 1-3m, Red >3m; color bar |
| **3.5** Implement altitude indicator with thresholds | Frontend | 0.75 | 1.1 | Target ~3.7m, Good ±0.15m, Monitor ±0.46m, Poor beyond ±0.46m |
| **3.6** Add no-data state for altitude (device dependency) | Frontend | 0.25 | 3.5 | Show placeholder if sprayHeight/radarAlt not available |
| **3.7** Add loading skeletons for all sections | Frontend | 0.75 | 2.1-3.6 | PrimeNG skeleton or custom shimmer; per widget |
| **3.8** Add empty state messages | Frontend | 0.5 | 3.7 | "No jobs assigned", "No data available", etc. |
| **3.9** Implement API error handling & fallbacks | Frontend | 0.75 | 1.3 | Toast notifications, graceful degradation |
| **3.10** Extract i18n strings (EN baseline) | Frontend | 0.5 | All sections | Update locale/en-Application.json, all $localize() calls |
| **3.11** Generate PT and ES translations | Frontend | 1.0 | 3.10 | Run xliffmerge workflow; validate no hardcoded English |
| **3.12** Test all chart responsiveness on mobile | Frontend | 0.5 | 3.1-3.3 | Charts stack/hide on small screens |
| **3.13** Unit tests for indicators, error handling, i18n | Frontend | 0.75 | 3.1-3.11 | Mock API responses, locale switching |

**Phase 3 Checkpoint:** Right column fully functional, all i18n ready, error scenarios handled.

**Commit Messages:**
```
feat(trends): add weekly trend charts with date range controls
feat(performance): add xt error and altitude indicators with threshold bands
feat(dashboard-state): add loading empty and error states for dashboard widgets
feat(i18n): localize pilot dashboard labels for en pt es
```

---

## Phase 4: QA, Integration & Release Hardening (4-5 Days)

### Deliverables
- Full end-to-end testing (mock and real backend if available)
- Role and permission isolation verification
- Cross-browser and device testing
- Performance and bundle size checks
- Release-ready build

### Tasks

| Task | Owner | Days | Dependencies | Notes |
|------|-------|------|--------------|-------|
| **4.1** Integration test: dashboard calls all 5 backend endpoints correctly | Frontend | 0.75 | 1.3 | Mock or real backend; verify request/response shapes |
| **4.2** Role isolation test: non-pilot roles see disclaimer only | Frontend | 0.5 | 1.5 | Test ADMIN, APP, OFFICER, CLIENT, INSPECTOR roles |
| **4.3** Responsive + mobile layout testing (Chrome, Safari, Firefox, Edge) | Frontend | 1.0 | All phases | Desktop, tablet, mobile; landscape/portrait |
| **4.4** Performance audit (performance and bundle impact) | Frontend | 0.5 | All phases | Record findings and optimize only if needed |
| **4.5** Regression testing: existing home for non-pilots unchanged | Frontend | 0.5 | 1.5 | Verify disclaimer still works; no side effects |
| **4.6** E2E tests (user flow: login → dashboard → click job → detail) | Frontend | 0.75 | 4.1-4.5 | Protractor or Cypress if available |
| **4.7** Lint, build, and final code review | Frontend | 0.5 | All phases | ng lint, ng build, tslint clean |
| **4.8** Documentation: user guide for pilot dashboard features | Frontend | 0.5 | All phases | README section, feature overview, known limitations |
| **4.9** Deployment dry-run and release notes | DevOps/Frontend | 0.5 | 4.7 | Build prod, verify localization (en/pt/es), changelog |

**Phase 4 Checkpoint:** Ready for staging and user acceptance testing.

**Commit Messages:**
```
test(dashboard): add e2e and integration tests
test(dashboard): add role isolation and regression tests
chore(dashboard): final ui polish and accessibility adjustments
docs(dashboard): add pilot dashboard user guide and feature summary
```

---

## 🔗 Backend Parallel Track (NOT included in frontend days)

**If backend endpoints do NOT exist yet, backend team should start immediately:**

| Task | Owner | Days | Dependencies |
|------|-------|------|--------------|
| **B.1** Design and implement 5 dashboard endpoints | Backend | 3-4 | Spec from 1.6 |
| **B.2** Add aggregation queries (KPI, trend, performance) | Backend | 2-3 | Database schema review |
| **B.3** Implement pilot data isolation (filter by Job.operator = pilotId) | Backend | 1-2 | Auth middleware |
| **B.4** Unit tests + load tests (concurrent dashboard calls) | Backend | 1-2 | B.1-B.3 |
| **B.5** Integration with frontend (live API testing) | Backend/Frontend | 1-2 | Phase 4.1 |

**Backend Total:** 8-13 days (parallel to Phase 2-3)

---

## 📅 Suggested Sprint Schedule

### Week 1 (Mon Apr 28 - Fri May 2)
- **Days 1-3:** Phase 1 (foundation, contracts, mock service)
- **Days 4-5:** Phase 2 start (layout, KPI cards)
- **PR 1 merged by EOW**

### Week 2 (Mon May 5 - Fri May 9)
- **Days 1-3:** Phase 2 complete (active jobs panel, responsive polish)
- **Days 4-5:** Phase 3 start (charts, date range)
- **PR 2 merged by EOW**

### Week 3 (Mon May 12 - Fri May 16)
- **Days 1-3:** Phase 3 continue (performance indicators, i18n)
- **Days 4-5:** Phase 3 complete (error states, final tests)
- **PR 3 merged by EOW**

### Week 4 (Mon May 19 - Fri May 23)
- **Days 1-3:** Phase 4 (integration testing, E2E, role isolation)
- **Days 4-5:** Phase 4 complete (perf audit, release prep)
- **PR 4 merged by EOW**

### Week 5 (Mon May 26 - Wed May 28)
- **Day 1:** Staging deployment, user acceptance testing
- **Days 2-3:** Bug fixes, final release sign-off

---

## Daily Time Breakdown (Typical)

Assuming 8-hour work day:

- **Development:** 5-6 hours
- **Testing (manual + automated):** 1-1.5 hours
- **Code review + feedback incorporation:** 0.5-1 hour
- **Documentation + commit messages:** 0.5 hour
- **Sync meetings (standup, demos):** 0.5 hour

---

## Critical Path & Blockers

### Critical Path
1. **Phase 1.6 (Backend spec)** must be done before backend team starts
2. **Phase 1.3 (Service layer)** must exist before Phase 2 UI work (can use mocks)
3. **Phase 2 (UI)** can proceed in parallel with backend if using mock data
4. **Phase 4.1 (Integration)** requires backend endpoints live

### Known Risks & Mitigation

| Risk | Impact | Mitigation |
|------|--------|-----------|
| Backend endpoints not ready | Phase 4 blocked | Use mock service in Phase 2-3; swap endpoints at Phase 4 |
| Status enum changes break existing jobs | High | Coordinate with backend; test all job statuses after enum change |
| i18n extraction tool issues | Phase 3 delayed | Pre-test localization workflow in Phase 1 |
| Chart.js version compatibility | Phase 3 blocked | Verify chart.js 2.9.3 works with PrimeNG 9.2.8 early in Phase 3.1 |
| Mobile responsive issues late | Phase 4 delay | Test mobile early (end of Phase 2), not Phase 4 |
| Job detail navigation broken | Phase 4 blocker | End-to-end test in Phase 2 with mock routing |

---

## Effort Distribution

```
Phase 1: ████░░░░░░░░░░░░░░  (22% - Foundation)
Phase 2: ███████░░░░░░░░░░░░ (30% - UI Core)
Phase 3: ██████░░░░░░░░░░░░░ (28% - Analytics + Polish)
Phase 4: ████░░░░░░░░░░░░░░░ (20% - QA + Release)
```

---

## Success Criteria (Definition of Done)

- [ ] All 12 steps implemented
- [ ] All 5 dashboard API endpoints wired and tested
- [ ] Pilot-only home working; non-pilots see original disclaimer
- [ ] Active jobs panel scrollable, clickable, color-coded
- [ ] Charts render with date range control
- [ ] Performance indicators show correct thresholds
- [ ] i18n works for EN, PT, ES
- [ ] No console errors or warnings
- [ ] Performance audit completed and documented
- [ ] Mobile responsive (320px to 1920px)
- [ ] Cross-browser tested (Chrome, Safari, Firefox, Edge)
- [ ] All 4 PRs merged and passed review
- [ ] Release notes and user guide complete

---

## Contingency Buffer

- **Unplanned blockers:** +2 days
- **Backend integration issues:** +1-2 days
- **UX revisions:** +1-2 days

**Total realistic completion:** 26-32 working days (5-6.5 weeks)

---

## Notes

1. **Mock Data:** Use throughout Phase 2-3 to avoid backend dependency blocking UI work.
2. **Commit Frequency:** Daily commits, PR every 1-2 days.
3. **Testing:** Continuous throughout all phases, not batched at end.
4. **Documentation:** Update README and include known limitations.
5. **Accessibility:** Test with keyboard nav, screen reader, high contrast mode.
6. **Performance:** Keep watch on bundle size; lazy-load charts if needed.

---

Generated: April 28, 2026  
Last Updated: April 28, 2026