# Agile Projects, Backlog, Sprints & Gantt — Implementation Report

## 1. Architecture decision: Tickets as work items

MVNexus already provides assignees, collaborators, comments, notes, attachments, status, priority, SLA, notifications, realtime, and audit logs on **Tickets**. A separate Task model would duplicate that surface area.

**Decision:** Extend `tickets` with nullable project/sprint/backlog fields. Helpdesk tickets remain unchanged when `project_id` is null. Project work uses `work_type` values (`backlog_item`, `project_task`, `bug`, `improvement`).

## 2. Data model

| Table | Purpose |
|-------|---------|
| `projects` | Department-scoped projects with status and due dates |
| `project_members` | Roles: owner, manager, member, viewer |
| `project_sprints` | Planned/active/closed sprints with timeline |
| `project_milestones` | Timeline markers (V1 data model; UI minimal) |
| `project_due_events` | Idempotent overdue notification markers |
| `tickets` (extended) | `project_id`, `sprint_id`, `work_type`, ordering, estimates, dates |

## 3. APIs

All under `/api/v1/projects` with Sanctum auth.

- CRUD projects, members, backlog, sprints, sprint tickets
- Move/reorder backlog and sprint items
- Gantt: `GET /projects/gantt`, `GET /projects/{project}/gantt`
- Overdue: `GET /projects/overdue`, `GET /projects/{project}/overdue`

## 4. Permissions

| Role | Scope |
|------|--------|
| Super Admin | All projects |
| Company Admin | Company projects |
| Department Head | Managed departments only |
| Project owner/manager | Project management |
| Project member/viewer | View; ticket updates per ticket policy |

Enforced in `ProjectPolicy` and `ProjectVisibilityService` (not frontend-only).

## 5. Due date rules

- **Project:** overdue if `due_date` past and status not completed/cancelled
- **Sprint:** overdue if `due_date` past and not closed
- **Ticket:** overdue if `due_date` past, not `completed_at`, status not closed

## 6. Notification rules

Types: `project_overdue`, `sprint_overdue`, `project_ticket_overdue`, `project_member_added`, `sprint_started`, `sprint_closed`.

- One fire per entity via `project_due_events.dedupe_key`
- `NotificationDedupeService` TTL for rapid duplicates
- EN/AR in-app and email templates in `NotificationTemplateSeeder`

Recipients follow spec (owner, managers, department head, assignee for tickets).

## 7. Gantt design

`ProjectGanttService` returns projects, milestones, sprints, work items, dependencies (`blocked_by_ticket_id`), completion %, overdue flags.

Frontend `GanttTimeline`: horizontal scroll, zoom controls, soft bars, overdue coloring.

## 8. Tests

**Backend** (`tests/Feature/Projects/ProjectApiTest.php`):

- Department head create/scoping
- Member access, backlog, sprint move, start/close
- Overdue dedupe
- Gantt scoping

**Frontend** (`resources/js/src/__tests__/unit/features/projects/ProjectsPage.test.tsx`):

- Loading skeleton, empty state, error/retry, forbidden (403), project cards, create modal

See also `docs/PROJECTS_PAGE_BLANK_STATE_FIX.md` for the `/projects` list page blank-state fix (pagination validation, UI states, index API enrichments).

## 9. Known gaps (V1)

- No drag/drop boards (safe reorder/move APIs only)
- Milestones API/UI not exposed (table ready)
- Velocity, burndown, capacity planning not implemented
- Cross-department membership only via admin/head override path

## 10. Future enhancements

- Story points velocity and burndown charts
- Scrum Sprint Board drag/drop with optimistic updates
- Full dependency graph on Gantt
- Milestone management UI
- Recurring sprint templates