libra/docs/epics/epic-4-case-timeline.md

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