# Case & Matter Management Module

This module organizes legal matters and their related tasks, documents and events. Cases progress through various stages with participants assigned to each matter.

## Database Schema

### matters
- `id` INT PRIMARY KEY
- `title` VARCHAR NOT NULL
- `description` TEXT nullable
- `client_id` INT
- `lead_attorney_id` INT
- `status` VARCHAR DEFAULT `Open`
- `opened_date` DATE
- `closed_date` DATE nullable
- `updatedSince` TIMESTAMP

### case_tasks
- `id` INT PRIMARY KEY
- `matter_id` INT FOREIGN KEY
- `subject` VARCHAR
- `due_date` DATETIME
- `assigned_to` INT
- `status` VARCHAR
- `updatedSince` TIMESTAMP

### case_documents
- `id` INT PRIMARY KEY
- `matter_id` INT FOREIGN KEY
- `file_name` VARCHAR
- `file_type` VARCHAR
- `file_path` TEXT
- `uploaded_at` DATETIME
- `uploaded_by` INT
- `updatedSince` TIMESTAMP

### case_events
- `id` INT PRIMARY KEY
- `matter_id` INT FOREIGN KEY
- `calendar_event_id` INT
- `description` TEXT
- `created_at` DATETIME
- `updatedSince` TIMESTAMP

### case_participants
- `id` INT PRIMARY KEY
- `matter_id` INT FOREIGN KEY
- `person_id` INT
- `role` VARCHAR
- `updatedSince` TIMESTAMP

### case_notes
- `id` INT PRIMARY KEY
- `matter_id` INT FOREIGN KEY
- `note` TEXT
- `created_by` INT
- `created_at` DATETIME
- `updatedSince` TIMESTAMP

## API Endpoints
Most resources expose CRUD actions under `../api/{resource}`.

### Matters
```
GET    ../api/matters
POST   ../api/matters
GET    ../api/matters/{id}
PUT    ../api/matters/{id}
DELETE ../api/matters/{id}
```

### Case Tasks
```
GET  ../api/case_tasks?matter_id={id}
POST ../api/case_tasks
```

### Case Documents
```
GET  ../api/case_documents?matter_id={id}
POST ../api/case_documents
POST ../api/case_documents/upload/{matterId}
GET  ../api/case_documents/download/{id}
GET  ../api/documents?case_id={id}
```

### Case Events
```
GET  ../api/case_events
POST ../api/case_events
```

### Participants
```
GET  ../api/case_participants
POST ../api/case_participants
```

### Notes
```
GET  ../api/case_notes?matter_id={id}
POST ../api/case_notes
```

## Offline Behaviour
`FrontEnd/JsLibs2/modules/CaseManagement/CaseHourApproval.js` uses `LocalSyncManager` to cache `matters`, `case_tasks`, `case_documents`, `case_events`, `case_participants` and `case_notes` in IndexedDB. Records created while offline are marked with `pendingSync` and pushed to the API when connectivity returns. Document uploads queue files for later transfer to the DMS.

## Integration Points
- **DMS** – `case_documents` leverage the Document Management System for storage and versioning via `DocumentsService`.
- **Calendar** – `case_events` link to `calendar_events` so hearings or meetings appear on users' calendars.
- **WorkflowEngine** – events like `case.created`, `case.statusChanged`, `case.opened`, `case.closed` and `matter.updated` trigger automated workflows for notifications or approvals.

### Workflow Events
The module emits the following events:
- `case.created` – a new case record was inserted.
- `case.statusChanged` – a case's status field changed.
- `matter.updated` – a matter record was updated.
## Invoice & Payment Workflow

Cases can generate client invoices and record payments. Financial data now uses
generic tables so multiple modules can share the same schema.  Three tables are
involved:
- **invoices** – contains all invoice records with a `type_id` and references to
  the related table/id.
- **payments** – records payments against an invoice and stores a `type_id`.
- **expenses** – general expense table keyed by `type_id` and a reference back
  to the case.

Administrators create forms named **Case Invoice**, **Case Payment** and **Case Expense** in the `forms` table.  These forms map to the generic tables above with the `type_id` for `case` prefilled so records are linked back to the matter.

The **Case Detail** modal defines *Invoices*, *Payments* and *Expenses* tabs. Each tab contains a button to open the corresponding form and a DataLoader table (`invoices`, `payments` or `expenses`).

### API Endpoints
```
POST ../api/invoices            # create invoice record
POST ../api/invoices/send/{id}  # mark an invoice as sent
GET  ../api/invoices/{id}/print # download invoice PDF
GET  ../api/invoices?case_id={id}
POST ../api/payments/recordPayment/{invoiceId} # record a payment
GET  ../api/payments?case_id={id}
POST ../api/expenses            # log a case expense
GET  ../api/expenses?case_id={id}
```

### Workflow Events
- `case.invoiceSent` – emitted when an invoice is sent.
- `case.paymentRecorded` – emitted after recording a payment.