# Epic 4: Case Timeline System

## Epic Goal

Implement a case tracking system where admin can create and update timelines for each client's legal matters, providing clients with read-only visibility into their case progress.

## Epic Description

### Business Context

Each client can have multiple legal cases/matters tracked through separate timelines. The admin adds text-based updates to keep clients informed of progress. This is strictly one-way communication - clients can view but cannot interact or respond.

### Technical Context

- **Timelines:** Multiple per client allowed
- **Updates:** Text-only (no document attachments)
- **Communication:** One-way (admin to client)
- **Status:** Active or Archived
- **Notifications:** Email on each update

### Success Criteria

- [ ] Admin can create unlimited timelines per client
- [ ] Admin can add text updates to timelines
- [ ] Admin can edit existing updates
- [ ] Admin can archive/unarchive timelines
- [ ] Clients can view their timelines (read-only)
- [ ] Clients notified via email on updates
- [ ] Update history with timestamps preserved
- [ ] Clear visual distinction between active/archived

---

## Stories

### Story 4.1: Timeline Creation

**Description:** Allow admin to create new case timelines for any client.

**Acceptance Criteria:**
- [ ] Create timeline form with:
  - Select client (search by name/email)
  - Case name/title (required)
  - Case reference number (optional, unique if provided)
  - Initial notes (optional)
- [ ] Timeline assigned to selected client
- [ ] Creation date automatically recorded
- [ ] Status defaults to 'active'
- [ ] Can create multiple timelines per client
- [ ] Confirmation on successful creation
- [ ] Timeline immediately visible to client

**Technical Notes:**
- Store in timelines table
- Fields: user_id, case_name, case_reference, status, created_at
- Validate case_reference uniqueness if provided

---

### Story 4.2: Timeline Updates Management

**Description:** Allow admin to add, edit, and manage updates within a timeline.

**Acceptance Criteria:**
- [ ] Add new update to timeline:
  - Update text content (required, rich text supported)
  - Timestamp automatically recorded
  - Admin name automatically recorded
- [ ] Edit existing updates:
  - Modify update text
  - Edit history preserved (updated_at changes)
- [ ] Updates displayed in chronological order
- [ ] Each update shows:
  - Date/timestamp
  - Admin name
  - Update content
- [ ] Visual timeline representation (optional enhancement)
- [ ] Client notified via email on new update

**Technical Notes:**
- Store in timeline_updates table
- Fields: timeline_id, admin_id, update_text, created_at, updated_at
- Track edit history via updated_at

---

### Story 4.3: Timeline Archiving

**Description:** Allow admin to archive completed cases and unarchive if needed.

**Acceptance Criteria:**
- [ ] Archive timeline:
  - Status changes to 'archived'
  - Timeline remains visible to client
  - No further updates can be added (until unarchived)
  - Visual indicator shows archived status
- [ ] Unarchive timeline:
  - Status returns to 'active'
  - Updates can be added again
- [ ] Filter timelines by status (active/archived)
- [ ] Bulk archive option for multiple timelines
- [ ] Archived timelines sorted separately in client view

**Technical Notes:**
- Use status field: 'active' or 'archived'
- Soft archive (no data deletion)

---

### Story 4.4: Admin Timeline Dashboard

**Description:** Central view for admin to manage all timelines across all clients.

**Acceptance Criteria:**
- [ ] List all timelines with:
  - Case name
  - Client name
  - Status (active/archived)
  - Last update date
  - Update count
- [ ] Filter by:
  - Client (search/select)
  - Status (active/archived/all)
  - Date range
- [ ] Sort by:
  - Client name
  - Case name
  - Last updated
  - Created date
- [ ] Quick actions:
  - View timeline details
  - Add update
  - Archive/unarchive
- [ ] Search by case name or reference
- [ ] Pagination for large lists

**Technical Notes:**
- Use Livewire for real-time filtering
- Eager load relationships to prevent N+1

---

### Story 4.5: Client Timeline View

**Description:** Read-only timeline view for clients to track their case progress.

**Acceptance Criteria:**
- [ ] List all client's timelines:
  - Active timelines prominently displayed
  - Archived timelines clearly separated
  - Visual distinction (color/icon) for status
- [ ] View individual timeline:
  - Case name and reference
  - Status indicator
  - All updates in chronological order
  - Each update with date and content
- [ ] No edit/comment capabilities
- [ ] No ability to archive/delete
- [ ] Responsive design for mobile viewing
- [ ] Recent updates indicator (new since last view)
- [ ] Bilingual labels and dates

**Technical Notes:**
- Filter by authenticated user's ID
- Track last_viewed timestamp per timeline (optional)
- Read-only Volt component

---

### Story 4.6: Timeline Update Notifications

**Description:** Email clients when admin adds updates to their timelines.

**Acceptance Criteria:**
- [ ] Email sent when new update added
- [ ] Email includes:
  - Case name/reference
  - Update summary or full text
  - Link to view timeline
  - Date of update
- [ ] Email in client's preferred language
- [ ] Sender: no-reply@libra.ps
- [ ] Professional template with branding
- [ ] No email for archived timeline reactivation
- [ ] Queue emails for performance

**Technical Notes:**
- Use Laravel notifications
- Trigger on timeline_updates creation
- Depends on Epic 8 for full email infrastructure

---

## Dependencies

| Epic | Dependency |
|------|------------|
| Epic 1 | Authentication, database schema |
| Epic 2 | User accounts (timelines assigned to users) |
| Epic 8 | Email notifications |

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Large update content performance | Low | Paginate updates, lazy load |
| Email notification failures | Medium | Queue with retry, log failures |
| Accidental archive of active case | Low | Confirmation dialog, unarchive option |

## Definition of Done

- [ ] All stories completed with acceptance criteria met
- [ ] Tests for timeline CRUD operations
- [ ] Tests for update management
- [ ] Tests for archive/unarchive
- [ ] Client view properly scoped to their timelines only
- [ ] Email notifications working
- [ ] Bilingual support verified
- [ ] Code formatted with Pint