# DocumentsController Refactoring Summary

## Overview
Removed all case-specific hardcoded logic from `DocumentsController` to achieve a fully generic, configuration-driven document management system that works with ANY entity type (cases, clients, projects, employees, etc.).

## Changes Made

### 1. create() Method (Lines 145-175)

**Before:**
```php
$caseId = $data['case_id'] ?? null;
unset($data['case_id']);

if ($caseId) {
    (new QueryBuilder())
        ->table('case_documents')
        ->insert([
            'case_id' => (int)$caseId,
            'document_id' => $id
        ]);
}
```

**After:**
```php
// NOTE: Entity linking (case_id, client_id, etc.) should be done via linkToEntity() endpoint
// The frontend calls /api/documents/link-to-entity after upload with entity_type, entity_id, and metadata
// Legacy case_documents table joins have been replaced with the generic document_metadata system
```

**Impact:**
- Document creation no longer handles entity linking directly
- Entity relationships are established via the `/api/documents/link-to-entity` endpoint after upload
- Uses the generic `document_metadata` table instead of the legacy `case_documents` junction table

### 2. getAll() Method (Lines 330-445)

**Before:**
```php
$caseId = isset($_GET['case_id']) ? (int)$_GET['case_id'] : null;

if ($caseId) {
    $qb->leftJoin('case_documents as cd', 'cd.document_id = d.document_id')
       ->where('cd.case_id', $caseId);
}
```

**After:**
```php
// Generic entity filtering via metadata
$entityType = $_GET['entity_type'] ?? null;
$entityId   = isset($_GET['entity_id']) ? (int)$_GET['entity_id'] : null;

// Legacy support: map case_id to entity filtering
if (!$entityType && isset($_GET['case_id'])) {
    $entityType = 'case';
    $entityId = (int)$_GET['case_id'];
}

if ($entityId && $entityType) {
    $metadataKey = $entityType . '_id';
    $qb->join('document_metadata as dm', 'dm.document_id = d.document_id')
       ->where('dm.metadata_key', $metadataKey)
       ->where('dm.metadata_value', (string)$entityId);
}
```

**Impact:**
- Filtering now works for ANY entity type via query parameters: `?entity_type=case&entity_id=123`
- Backward compatibility maintained: old `?case_id=123` calls are automatically mapped to entity filtering
- Uses `document_metadata` table joins instead of `case_documents` table
- Pattern: `metadata_key = '{entity_type}_id'` and `metadata_value = '{entity_id}'`

## API Usage Examples

### Create Document (Upload)
```javascript
// Step 1: Create document record
POST /api/documents/create
{
  "title": "Contract Draft",
  "filename": "contract.pdf",
  "type": "contract",
  // NO entity_id or case_id here
}

// Returns: { "id": 456 }
```

### Link Document to Entity
```javascript
// Step 2: Link to entity with metadata
POST /api/documents/link-to-entity
{
  "document_id": 456,
  "entity_type": "case",
  "entity_id": 123,
  "entity_data": {
    "case_number": "MC001",
    "case_title": "Smith vs. State",
    "client_id": 789,
    "client_name": "John Smith",
    "matter_type": "criminal",
    "status": "active"
  },
  "source_context": "case_management",
  "custom_tags": ["legal", "urgent"]
}
```

### Retrieve Documents for Entity

**New way (generic):**
```javascript
GET /api/documents?entity_type=case&entity_id=123
GET /api/documents?entity_type=client&entity_id=789
GET /api/documents?entity_type=project&entity_id=456
```

**Old way (still works for backward compatibility):**
```javascript
GET /api/documents?case_id=123
// Automatically mapped to: entity_type=case&entity_id=123
```

### Filter by Tag and Entity
```javascript
GET /api/documents?tag=legal&entity_type=case&entity_id=123
```

## Database Schema

### document_metadata Table
Stores all entity relationships and custom metadata:
```sql
CREATE TABLE document_metadata (
    metadata_id SERIAL PRIMARY KEY,
    document_id INT NOT NULL,
    metadata_key VARCHAR(255) NOT NULL,     -- e.g., "case_id", "client_id", "case_number"
    metadata_value TEXT,                    -- e.g., "123", "789", "MC001"
    value_type VARCHAR(50) DEFAULT 'text',  -- text, number, date, json
    searchable BOOLEAN DEFAULT true,
    indexed BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (document_id) REFERENCES documents(document_id) ON DELETE CASCADE
);
```

### Query Pattern
Documents are linked via metadata entries:
```sql
-- Link document to case
INSERT INTO document_metadata (document_id, metadata_key, metadata_value)
VALUES (456, 'case_id', '123');

-- Retrieve documents for case
SELECT d.* 
FROM documents d
JOIN document_metadata dm ON dm.document_id = d.document_id
WHERE dm.metadata_key = 'case_id' 
  AND dm.metadata_value = '123';
```

## Frontend Configuration

Documents tab in `sql/modules.sql`:
```json
{
  "type": "documents",
  "options": {
    "filterField": "case_id",
    "metadataFields": {
      "case_number": "case_number",
      "case_title": "title",
      "client_id": "client_id",
      "client_name": "client_name",
      "matter_type": "matter_type",
      "status": "status"
    }
  }
}
```

ModalBuilder extracts metadata from the current record:
```javascript
const metadataFields = element.options.metadataFields;
const entityData = {};

for (const [metadataKey, recordField] of Object.entries(metadataFields)) {
  const value = recordField.includes('.') 
    ? recordField.split('.').reduce((obj, key) => obj?.[key], this.record)
    : this.record[recordField];
  entityData[metadataKey] = value || '';
}
```

## Benefits

1. **Complete Generic Architecture**: Works with ANY entity type without code changes
2. **Configuration-Driven**: Add new entity types by updating module JSON only
3. **Metadata Rich**: Store unlimited custom metadata per document
4. **Backward Compatible**: Legacy `case_id` parameter still works
5. **Searchable**: All metadata can be indexed and searched
6. **No Junction Tables**: Single `document_metadata` table replaces all entity-specific tables
7. **Hierarchical Tags**: Auto-generated system tags (e.g., "case:MC001")

## Migration Notes

### For Frontend Code
**Old pattern:**
```javascript
// Upload with case_id
uploadDocument({ case_id: 123, ... });
```

**New pattern:**
```javascript
// Upload, then link
const doc = await uploadDocument({ ... });
await linkDocument(doc.id, 'case', 123, entityData);
```

### For Database Queries
**Old pattern:**
```sql
SELECT d.* 
FROM documents d
JOIN case_documents cd ON cd.document_id = d.document_id
WHERE cd.case_id = 123;
```

**New pattern:**
```sql
SELECT d.* 
FROM documents d
JOIN document_metadata dm ON dm.document_id = d.document_id
WHERE dm.metadata_key = 'case_id' 
  AND dm.metadata_value = '123';
```

## Testing Checklist

- [ ] Upload document from case management module
- [ ] Verify metadata stored in `document_metadata` table
- [ ] Retrieve documents by `case_id` (legacy parameter)
- [ ] Retrieve documents by `entity_type=case&entity_id=123`
- [ ] Filter documents by tag + entity
- [ ] Upload document from client module (test with different entity type)
- [ ] Upload document from project module (test with different entity type)
- [ ] Verify backward compatibility with existing frontends using `case_id`
- [ ] Check that document search includes metadata fields
- [ ] Verify auto-generated system tags (e.g., "case:MC001")

## Future Enhancements

1. **Deprecate case_documents table**: Once all code is migrated, remove legacy table
2. **Metadata indexing**: Add full-text search across metadata values
3. **Rich metadata types**: Support JSON, date ranges, geolocation in metadata
4. **Metadata templates**: Pre-defined metadata schemas per entity type
5. **Bulk linking**: Link multiple documents to entity in single API call
6. **Metadata history**: Track changes to document metadata over time

## Related Files

- `TAFDB.pgsql` - Database schema with `document_metadata` and `document_tags` tables
- `models/Documents.php` - Data access layer with `getEntityDocuments()` method
- `api/controllers/DocumentsController.php` - This file (refactored)
- `FrontEnd/js/core/ModalBuilder.js` - Configuration-driven metadata extraction
- `FrontEnd/js/helpers/documentHelpers.js` - Frontend helper functions
- `sql/modules.sql` - Module configurations with `metadataFields`
- `docs/GenericDocumentSystem.md` - Complete system documentation

## Summary

All case-specific hardcoded logic has been successfully removed from `DocumentsController`. The system is now fully generic and works with ANY entity type through:

1. **Generic Parameters**: `entity_type` + `entity_id` instead of hardcoded `case_id`
2. **Metadata-Based Filtering**: Queries `document_metadata` table instead of junction tables
3. **Configuration-Driven Frontend**: Metadata captured via `metadataFields` in module JSON
4. **Backward Compatibility**: Legacy `case_id` parameter automatically mapped to entity filtering
5. **Zero Code Changes**: New entity types supported by configuration only

The entire stack is now entity-agnostic: Database → Model → Controller → Frontend.