# Agile Architecture Impact Report

## Gap analysis vs Jira / Azure DevOps / ClickUp

| Capability | Jira | Azure DevOps | ClickUp | MVNexus (before) | MVNexus (target) |
|------------|------|--------------|---------|---------------------|---------------------|
| Work item vs incident split | Issue types | Work Item vs Bug | Task vs Ticket | Implicit `work_type` only | **`ticket_type`** first-class |
| Product backlog UX | Rich backlog + filters | Backlog | List + sprints | Minimal list | **Metrics, filters, epic groups, cards** |
| Sprint planning | Drag backlog → sprint | Sprint planning | Sprint view | Button only | **Planning screen DnD** |
| Sprint management | Sprint list | Iterations | Spaces/Folders | No list page | **Sprints page** |
| Work item detail | Issue view | Work item form | Task view | Support ticket page | **Agile work item page** |
| Acceptance criteria | Custom field / checklist | Acceptance criteria | Checklists | None | **Checklist API + UI** |
| Epic grouping | Epic link | Feature | Epic | Gantt only | **Backlog group by epic** |
| Story points + MD | Both | Points + remaining | Points | MD only | **MD primary, SP optional** |
| Time tracking | Optional | Remaining work | Time | Hidden MD | **Feature flag off** |

## Architectural correction

- **Same table:** `tickets`
- **Discriminator:** `ticket_type` ∈ `support_ticket` | `project_work_item`
- **Subtype:** `work_type` (story, bug, backlog_item, …) for agile items only
- Support tickets: unchanged SLA/replies/notes workflow
- Project work items: agile UI only; route `/projects/:projectId/work-items/:id`

## Database changes

| Change | Migration |
|--------|-----------|
| `tickets.ticket_type` | `2026_06_08_100000_ticket_type_and_acceptance_criteria.php` |
| `work_item_acceptance_criteria` | same |
| Backfill `project_work_item` where `project_id` not null | same |

## API changes

| Endpoint | Purpose |
|----------|---------|
| `GET /projects/{id}/backlog?group_by=epic` | Metrics + items or epic groups |
| `GET/PATCH /projects/{id}/work-items/{ticket}` | Agile detail |
| `GET/POST/PATCH/DELETE .../acceptance-criteria` | Checklist |
| `POST .../work-items/{ticket}/clone` | Clone item |
| Ticket list | Excludes `project_work_item` |

## Frontend pages

| Page | Route |
|------|-------|
| Product Backlog (redesign) | `/projects/:id/backlog` |
| Sprints | `/projects/:id/sprints` |
| Sprint Planning | `/projects/:id/sprint-planning` |
| Work Item Detail | `/projects/:id/work-items/:ticketId` |
| Project Overview (dashboard widgets) | `/projects/:id` |

## Permissions

Unchanged: `ProjectPolicy` for project routes; `TicketPolicy` for work item view/update by department + visibility. Project members see project via `ProjectVisibilityService`.

## Migration plan

1. Deploy migration (additive).
2. Backfill `ticket_type`.
3. Deploy API + frontend.
4. Redirect `/tickets/:id` → work item route when `project_work_item`.

## Backward compatibility

- Existing rows: backfilled automatically.
- `work_type` retained.
- Support tickets: `ticket_type = support_ticket`.
- Old links to `/tickets/:id` for work items redirect to agile page.

## Validation checklist

- [ ] Support ticket create → `support_ticket`
- [ ] Backlog create → `project_work_item`
- [ ] `/tickets` list excludes project items
- [ ] Work item opens agile page, not SLA/replies layout
- [ ] Backlog metrics and epic grouping
- [ ] Sprint planning drag-drop
- [ ] Acceptance criteria CRUD
- [ ] `AGILE_TIME_TRACKING_ENABLED=false` hides timer UI

## Implementation phases

1. **Foundation** — `ticket_type`, config, resources, list filter
2. **Backlog** — API metrics, UI redesign, cards
3. **Work item** — Detail API + tabbed page
4. **Sprints** — List + planning pages
5. **Polish** — Dashboard widgets, subnav, tests