templates: add multi-category filter (repeatable or CSV) to GET /api/templates/search; add has_keywords filter; add categories listing endpoint with counts; update docs; add tests

2025-08-15 15:04:40 -05:00
parent 21c6b285d6
commit e3a279dba7
17 changed files with 3727 additions and 2 deletions
--- a/docs/LEGACY_SYSTEM_ANALYSIS.md
+++ b/docs/LEGACY_SYSTEM_ANALYSIS.md
@@ -0,0 +1,411 @@
+# Legacy System Analysis: Delphi Consulting Group Database
+
+## Executive Summary
+
+This document provides a comprehensive analysis of the legacy Paradox-based database system used by Delphi Consulting Group, based on examination of the .sc (script) files found in the `old database` folder. The legacy system was a sophisticated legal practice management application specialized for family law attorneys handling divorce cases involving pension plan division (QDROs).
+
+## System Architecture Overview
+
+### Technology Stack
+- **Platform**: Paradox Database Management System
+- **Language**: PAL (Paradox Application Language)
+- **Integration**: WordPerfect document assembly
+- **File Structure**: Modular .SC script files with shared procedure library
+
+### Core Directory Structure
+```
+R:\PDOXDATA\OFFICE\     # Main data directory
+R:\DOCUMENT\WPDOCS\     # WordPerfect documents
+R:\PRIVATE\             # Temporary/merge files
+OFFICE.LIB              # Shared procedure library
+```
+
+## Module-by-Module Analysis
+
+### 1. Main Application Entry (`Main_RH.SC`)
+
+**Purpose**: Application bootstrap and main menu system
+
+**Key Features**:
+- Splash screen with company branding
+- Hierarchical pulldown menu system
+- Library and configuration management
+- Keyboard shortcut definitions
+
+**Menu Structure**:
+```
+Open
+├── Rolodex (contact management)
+├── File Cabinet (case management)
+├── QDRO Screen (pension division documents)
+├── Plan Information (retirement plan database)
+├── Annuity Evaluator (present value calculations)
+└── Deposit Book (banking records)
+
+Utilities
+├── Basic Data (lookup tables)
+└── Tally Accounts (financial reconciliation)
+
+System
+├── Customize (letterhead/branding)
+└── Printers (output configuration)
+```
+
+**Startup Sequence**:
+1. Load procedure library (OFFICE.LIB)
+2. Initialize directory paths and variables
+3. Display animated splash screen
+4. Launch main menu loop
+5. Handle user selections via switch statements
+
+### 2. Contact Management (`ROLODEX.SC`)
+
+**Purpose**: Comprehensive contact database for clients, opposing counsel, and related parties
+
+**Data Structure**:
+- **Primary Table**: Rolodex (main contact info)
+- **Related Tables**: Phone (multiple numbers per contact)
+- **Indexing**: By ID, last name, group classification
+
+**Key Features**:
+
+**Multi-Form Interface**:
+- Form 1: Standard contact entry
+- Form 4: Detailed view with extended information
+- Alt-F: Toggle between forms
+
+**Search Capabilities**:
+- Multi-criteria search dialog
+- ID, name, address, phone number filters
+- Group-based filtering (client, opposing counsel, personal)
+- Phone number cross-referencing
+
+**Integration Points**:
+- File cabinet owner/opposing party lookups
+- Document assembly merge fields
+- Envelope and label generation
+- Phone book report generation
+
+**Report Types**:
+- Envelope generation
+- Phone book (numbers only)
+- Phone book with addresses
+- Complete rolodex information
+
+### 3. File Cabinet System (`FILCABNT.SC`)
+
+**Purpose**: Case management with integrated time and billing
+
+**Architecture**: Master-Detail relationship
+- **Master**: Files table (case information, account summaries)
+- **Detail**: Ledger table (time entries, disbursements, payments)
+
+**File Management Features**:
+
+**Case Information**:
+- Unique file numbers
+- Client assignment (linked to Rolodex)
+- Area of law classification
+- Open/close date tracking
+- Status management (ACTIVE, INACTIVE, FOLLOW UP, etc.)
+- Opposing counsel assignment
+- Billing rate assignment by employee
+
+**Account Management**:
+- Real-time balance calculations
+- Trust account tracking
+- Hourly fees, flat fees, disbursements
+- Credit/payment tracking
+- Transferable amount calculations (trust → fees)
+- Previously billed vs. current balance separation
+
+**Advanced Features**:
+
+**Time Tracking**:
+- Built-in timer (Alt-T start/stop)
+- Elapsed time display with hours:minutes:seconds
+- Automatic time entry integration
+
+**Account Operations**:
+- Account closure (Alt-C): Automatically closes file and creates payment entry
+- Account reopening (Alt-R): Reverses closure process
+- Balance summarization (Alt-B): Popup with detailed breakdowns
+
+**Search and Reporting**:
+- Complex multi-criteria search
+- Account balance filters
+- File status filtering (SEND/HOLD for statement printing)
+- Multiple report formats (detailed, summary, statements)
+
+### 4. Ledger/Billing System (`LEDGER.SC`)
+
+**Purpose**: Transaction-level time and billing management
+
+**Transaction Types**:
+1. **Type 1**: Trust account entries
+2. **Type 2**: Hourly time entries (quantity × rate)
+3. **Type 3**: Flat fee charges
+4. **Type 4**: Disbursements/expenses
+5. **Type 5**: Credits/payments
+
+**Data Entry Features**:
+
+**Automatic Calculations**:
+- Quantity × Rate = Amount for hourly entries
+- Employee rate lookups from Employee table
+- Real-time amount recalculation on field changes
+
+**Validation and Business Rules**:
+- Required fields: Date, Transaction Code, Employee, Amount
+- Automatic item number assignment (handles key violations)
+- Billed status tracking (Y/N)
+- Default employee assignment from parent file
+
+**Advanced Entry Features**:
+- Insert new records (INS key) with date inheritance
+- Quick billed status toggle (Alt-Y/Alt-N)
+- Date increment/decrement (+/- keys)
+- Integrated balance summarization
+
+**Account Reconciliation**:
+- Real-time account total updates on record changes
+- Separation of billed vs. unbilled amounts
+- Trust account balance calculations
+- Transferable amount determination
+
+### 5. QDRO Module (`QDRO.SC`)
+
+**Purpose**: Qualified Domestic Relations Order document preparation
+
+**Specialized Features**:
+- QDRO-specific data entry forms
+- Integration with document assembly system
+- Version tracking for QDRO revisions
+- User-specific output table generation
+
+**Document Generation Process**:
+1. Data entry in QDRO table
+2. Copy to temporary output table (Q_Output or user-specific)
+3. File number versioning ([File_No] + [Version])
+4. Integration with form selection system
+5. Automatic cleanup of temporary tables
+
+### 6. Setup and Configuration (`SETUP.SC`)
+
+**Purpose**: Lookup table management and system configuration
+
+**Managed Tables**:
+
+**Basic Data Tables**:
+- **FileType**: Areas of law (divorce, personal injury, etc.)
+- **Employee**: Attorney/staff information with billing rates
+- **TrnsType**: Transaction groupings for accounting
+- **Footers**: Statement footer text templates
+- **GrupLkup**: Rolodex group classifications
+- **TrnsLkup**: Transaction codes and descriptions
+- **FileStat**: File status definitions with print settings
+- **States**: State abbreviations and full names
+- **Printers**: Printer configuration and setup strings
+
+**Table Management Features**:
+- Uniform editing interface across all lookup tables
+- Field-specific prompts and help text
+- Form-based entry with validation
+- Print report capabilities for each table
+- Context-sensitive speedbar help
+
+**Special Processing**:
+- **Deposits**: Automatic payment totaling
+- **Date manipulation**: +/- key support for date fields
+- **Printer setup**: Integration with printer configuration
+
+### 7. Document Assembly System (`FORM_MGR.SC`)
+
+**Purpose**: Sophisticated legal document generation system
+
+**Architecture**:
+- **Form Library**: Searchable database of document templates
+- **Index System**: Keyword-based form categorization
+- **Merge Process**: Data extraction and WordPerfect integration
+
+**Form Management**:
+
+**Form Selection Interface**:
+- Directory browsing with form file listings
+- Form description database integration
+- Multi-form selection capabilities
+- Search by name, description, status, keywords
+
+**Search Capabilities**:
+- Text-based searching (name, description, status)
+- Keyword index searching with dynamic arrays
+- Boolean search combinations
+- User-friendly selection interface
+
+**Document Generation Process**:
+1. **Form Selection**: Browse and select multiple forms
+2. **Data Extraction**: Query current data set for merge fields
+3. **Configuration File**: Generate merge instruction file
+4. **External Processing**: Execute DOS batch file (GO.BAT)
+5. **WordPerfect Integration**: Automatic document assembly
+
+**Technical Implementation**:
+- Dynamic array management for form lists
+- File system integration for template discovery
+- Automatic data export for merge process
+- Error handling for missing templates
+
+### 8. Utility Functions (`UTILITY.SC`)
+
+**Purpose**: Shared utility procedures used throughout the system
+
+**Core Utilities**:
+
+**Mode Management**:
+- `Edit_Mode()`: Switch to data editing mode
+- `Main_Mode()`: Return to read-only mode
+- `Clear_Table()`: Exit current data view
+
+**User Interface**:
+- `Message_Box()`: Standard dialog messages
+- `Yes_No_Cancel()`: Three-button confirmation dialogs
+- `Response_Is_Yes()`: Binary confirmation dialogs
+- `Sound_Off()`: Audio feedback system
+
+**System Configuration**:
+- `Get_Custom_Setup_Variables()`: Load company settings
+- `Customize_Setup()`: Edit letterhead and branding
+- Printer configuration and management
+- Default printer selection
+
+**Reporting Infrastructure**:
+- `Print_Report()`: Universal report output handler
+- Destination selection (printer/screen/file)
+- Escape sequence processing for printer codes
+- File output with overwrite protection
+
+**Data Management**:
+- `Organize()`: Archive file management (ARCHIVE status handling)
+- `Update_Calendar()`: Appointment archival system
+- Printer status checking and error handling
+
+## Business Domain Analysis
+
+### Legal Practice Specialization
+
+**Target Market**: Family law attorneys specializing in divorce cases involving retirement benefit division
+
+**Core Competencies**:
+1. **QDRO Expertise**: Qualified Domestic Relations Orders for pension division
+2. **Complex Asset Division**: Retirement plan valuation and division
+3. **Time and Billing**: Specialized legal billing requirements
+4. **Document Generation**: Automated legal document preparation
+
+### Workflow Integration
+
+**Typical Case Flow**:
+1. **Client Intake**: Rolodex entry with contact information
+2. **File Opening**: Create case file with billing parameters
+3. **Time Tracking**: Record attorney/staff time with built-in timer
+4. **Document Preparation**: Select and generate legal documents
+5. **QDRO Drafting**: Specialized pension division order preparation
+6. **Billing**: Generate statements and track payments
+7. **Case Closure**: Automatic account reconciliation
+
+### Advanced Features
+
+**Financial Management**:
+- Trust account IOLTA compliance tracking
+- Separate billed/unbilled amount tracking
+- Automatic transferable amount calculations
+- Statement generation with customizable footers
+
+**Document Automation**:
+- Template library with keyword indexing
+- Automated data merge with WordPerfect
+- Version control for document revisions
+- Batch document generation capabilities
+
+## Technical Architecture Patterns
+
+### Event-Driven Programming
+- Standardized `WAIT WORKSPACE` event loops
+- Consistent key binding patterns (F2=Save, F8=Clear, F9=Edit)
+- Menu-driven interactions with hierarchical structure
+- Trigger-based field and record validation
+
+### Data Validation Framework
+- Field-level validation on departure
+- Record-level validation before posting
+- Business rule enforcement (required fields, calculations)
+- Automatic default value assignment
+
+### Master-Detail Relationships
+- Files ↔ Ledger (1:many) with automatic totaling
+- Rolodex ↔ Phone (1:many) with contact integration
+- Files ↔ Rolodex (many:1) for client/opposing party references
+- Form ↔ Index (1:many) for document categorization
+
+### Search and Query Patterns
+- Dynamic query building with user criteria
+- Complex multi-table joins for reporting
+- Pattern matching with wildcard support
+- Result set management with subset tables
+
+### User Experience Design
+- Context-sensitive help and prompts
+- Consistent speedbar layouts
+- Progressive disclosure in menu systems
+- Modal dialog standardization
+
+## Integration Points
+
+### External System Integration
+- **WordPerfect**: Document merge and generation
+- **DOS**: Batch file execution for complex operations
+- **Printer Systems**: Direct escape sequence management
+- **File System**: Template and configuration file management
+
+### Data Export/Import
+- Configuration file generation for merges
+- Report output to multiple formats (printer/screen/file)
+- Automatic data extraction for document assembly
+- Archive and reorganization utilities
+
+## Performance and Scalability Considerations
+
+### Database Design
+- Indexed access patterns for fast lookups
+- Efficient master-detail navigation
+- Query optimization with selective criteria
+- Memory management with dynamic arrays
+
+### User Interface Responsiveness
+- Immediate feedback for user actions
+- Progress indicators for long operations
+- Background processing for reports
+- Efficient screen updates with ECHO control
+
+## Security and Data Integrity
+
+### Access Control
+- User-based table access (seen in QDRO user checking)
+- Function-level security through menu disabling
+- Data validation to prevent corruption
+
+### Backup and Recovery
+- Archive table management for historical data
+- Automatic data reorganization utilities
+- Printer and configuration backup systems
+
+## Conclusion
+
+The legacy system represents a sophisticated, domain-specific application with deep understanding of legal practice management needs. Key strengths include:
+
+1. **Specialized Legal Functionality**: QDRO expertise and legal document automation
+2. **Integrated Financial Management**: Complex billing with trust account compliance
+3. **Advanced User Interface**: Consistent, efficient data entry patterns
+4. **Document Assembly Integration**: Sophisticated template and merge system
+5. **Comprehensive Reporting**: Multiple output formats with printer management
+
+The system demonstrates mature software architecture principles adapted to the constraints and capabilities of the Paradox platform, with particular excellence in the specialized domain of family law practice management.
--- a/docs/MISSING_FEATURES_TODO.md
+++ b/docs/MISSING_FEATURES_TODO.md
@@ -0,0 +1,462 @@
+# Missing Features TODO List
+
+## Overview
+
+Based on the comprehensive analysis of the legacy Paradox system, this document outlines all features present in the original system but missing from the current FastAPI implementation. Items are prioritized by business impact and implementation complexity.
+
+---
+
+## HIGH PRIORITY - Core Business Features
+
+### 🔴 1. Document Assembly System
+
+**Legacy Feature**: Sophisticated legal document generation with WordPerfect integration
+
+**Current Status**: ❌ Not implemented
+
+**Required Components**:
+
+#### 1.1 Document Template Management
+- [ ] Create `DocumentTemplate` model
+  - Template name, description, file path
+  - Category/area of law classification
+  - Status (active/inactive)
+  - Version tracking
+- [ ] Template upload and storage system
+- [ ] Template preview capabilities
+- [ ] Template search and filtering
+
+#### 1.2 Template Keyword/Index System
+- [ ] Create `TemplateKeyword` model for searchable tags
+- [ ] Keyword management interface
+- [ ] Advanced template search by keywords
+- [ ] Template categorization system
+
+#### 1.3 Data Merge Engine
+- [ ] Variable extraction from current data context
+- [ ] Merge field mapping system
+- [ ] Template variable substitution engine
+- [ ] Support for multiple output formats (PDF, DOCX)
+
+#### 1.4 Form Selection Interface
+- [ ] Multi-template selection UI
+- [ ] Template preview and description display
+- [ ] Batch document generation
+- [ ] Generated document management
+
+**API Endpoints Needed**:
+```
+POST   /api/templates/upload
+GET    /api/templates/search
+POST   /api/templates/{id}/merge
+GET    /api/templates/{id}/preview
+POST   /api/documents/generate-batch
+```
+
+### 🔴 2. QDRO (Pension Division) Module
+
+**Legacy Feature**: Specialized module for Qualified Domestic Relations Orders
+
+**Current Status**: ❌ Not implemented
+
+**Required Components**:
+
+#### 2.1 QDRO Data Model
+- [ ] Create `QDRO` model
+  - File number reference
+  - Version tracking
+  - Plan information (name, type, administrator)
+  - Participant details (employee, spouse/ex-spouse)
+  - Division methodology (percentage, dollar amount, etc.)
+  - Effective dates and conditions
+- [ ] Plan information database
+- [ ] QDRO version management
+
+#### 2.2 QDRO-Specific Forms
+- [ ] QDRO data entry interface
+- [ ] Plan information management
+- [ ] Participant role management
+- [ ] Division calculation tools
+
+#### 2.3 QDRO Document Generation
+- [ ] QDRO-specific templates
+- [ ] Integration with document assembly system
+- [ ] Version control for QDRO revisions
+- [ ] Court approval tracking
+
+**API Endpoints Needed**:
+```
+POST   /api/qdros
+GET    /api/qdros/{file_no}
+PUT    /api/qdros/{id}
+POST   /api/qdros/{id}/generate-document
+GET    /api/qdros/{id}/versions
+POST   /api/plan-info
+```
+
+### 🔴 3. Advanced Billing & Statement Generation
+
+**Legacy Feature**: Automated billing statement generation with trust account management
+
+**Current Status**: ⚠️ Partially implemented (basic transactions exist)
+
+**Missing Components**:
+
+#### 3.1 Statement Generation Engine
+- [ ] Create billing statement templates
+- [ ] Automated statement generation by file/client
+- [ ] Customizable statement footers by file status
+- [ ] Statement preview and approval workflow
+- [ ] Batch statement generation
+
+#### 3.2 Enhanced Trust Account Management
+- [ ] Extend trust account transaction types
+- [ ] Trust account balance tracking per file
+- [ ] IOLTA compliance reporting
+- [ ] Trust-to-fee transfer automation
+- [ ] Trust account reconciliation tools
+
+#### 3.3 Billing Workflow Management
+- [ ] Billed/unbilled transaction status tracking
+- [ ] Bulk billing status updates
+- [ ] Statement approval and locking
+- [ ] Payment application workflow
+- [ ] Account aging reports
+
+#### 3.4 Advanced Financial Reports
+- [ ] Account balance summaries by employee
+- [ ] Account aging reports
+- [ ] Trust account activity reports
+- [ ] Revenue reports by area of law
+- [ ] Time utilization reports
+
+**API Endpoints Needed**:
+```
+POST   /api/billing/statements/generate
+GET    /api/billing/statements/{file_no}
+POST   /api/billing/statements/batch
+PUT    /api/financial/transactions/bulk-bill
+GET    /api/reports/trust-account
+GET    /api/reports/account-aging
+```
+
+---
+
+## MEDIUM PRIORITY - Productivity Features
+
+### 🟡 4. Integrated Time Tracking
+
+**Legacy Feature**: Built-in timer with start/stop functionality
+
+**Current Status**: ❌ Not implemented
+
+**Required Components**:
+
+#### 4.1 Timer System
+- [ ] Real-time timer with start/stop/pause
+- [ ] Timer state persistence across sessions
+- [ ] Multiple concurrent timers by file/task
+- [ ] Timer integration with transaction entry
+
+#### 4.2 Time Entry Automation
+- [ ] Auto-populate time entries from timer
+- [ ] Default rate assignment by employee
+- [ ] Automatic quantity calculation
+- [ ] Timer history and reporting
+
+**Frontend Components**:
+```
+TimerWidget
+├── Timer display (HH:MM:SS)
+├── Start/Stop/Pause controls
+├── File/task selection
+└── Quick time entry creation
+```
+
+**API Endpoints Needed**:
+```
+POST   /api/timers/start
+POST   /api/timers/{id}/stop
+GET    /api/timers/active
+POST   /api/timers/{id}/create-entry
+```
+
+### 🟡 5. Enhanced File Management
+
+**Legacy Feature**: Advanced file operations and status management
+
+**Current Status**: ⚠️ Basic file management exists
+
+**Missing Components**:
+
+#### 5.1 File Closure Automation
+- [ ] Automatic file closure workflow
+- [ ] Outstanding balance payment entry creation
+- [ ] File closure validation and confirmations
+- [ ] File reopening capabilities
+
+#### 5.2 File Status Workflow
+- [ ] Enhanced file status definitions
+- [ ] Status-based business rule enforcement
+- [ ] Automatic status transitions
+- [ ] Status history tracking
+
+#### 5.3 File Organization
+- [ ] Archive file management
+- [ ] Bulk file status updates
+- [ ] File transfer between attorneys
+- [ ] File merge capabilities
+
+**API Endpoints Needed**:
+```
+POST   /api/files/{id}/close
+POST   /api/files/{id}/reopen
+POST   /api/files/bulk-status-update
+POST   /api/files/{id}/transfer
+```
+
+### 🟡 6. Advanced Printer Management
+
+**Legacy Feature**: Sophisticated printer configuration and report formatting
+
+**Current Status**: ❌ Not implemented
+
+**Required Components**:
+
+#### 6.1 Printer Configuration
+- [ ] Printer setup database
+- [ ] Escape sequence management
+- [ ] Default printer selection
+- [ ] Report-specific printer settings
+
+#### 6.2 Report Output Management
+- [ ] Multiple output destinations (printer/screen/file)
+- [ ] Print preview functionality
+- [ ] Batch printing capabilities
+- [ ] Print queue management
+
+**Note**: Modern web applications typically rely on browser printing, but for a legal office, direct printer control might still be valuable.
+
+---
+
+## LOW PRIORITY - Nice-to-Have Features
+
+### 🟢 7. Calendar/Appointment System
+
+**Legacy Feature**: Calendar management with appointment archival
+
+**Current Status**: ❌ Not implemented
+
+**Required Components**:
+
+#### 7.1 Calendar Management
+- [ ] Create `Calendar` and `Appointment` models
+- [ ] Calendar views (day/week/month)
+- [ ] Appointment scheduling and management
+- [ ] Conflict detection and resolution
+
+#### 7.2 Integration Features
+- [ ] File-related appointment linking
+- [ ] Court date tracking
+- [ ] Deadline management
+- [ ] Automatic archival of old appointments
+
+### 🟢 8. Enhanced Lookup Table Management
+
+**Legacy Feature**: Comprehensive lookup table administration
+
+**Current Status**: ⚠️ Basic lookup management exists
+
+**Missing Components**:
+
+#### 8.1 Advanced Lookup Management
+- [ ] Dynamic lookup table creation
+- [ ] Lookup table relationships
+- [ ] Import/export of lookup data
+- [ ] Lookup table versioning
+
+#### 8.2 Business Rule Configuration
+- [ ] Configurable validation rules
+- [ ] Dynamic field requirements
+- [ ] Custom calculation formulas
+- [ ] Workflow automation rules
+
+### 🟢 9. Enhanced Search Capabilities
+
+**Legacy Feature**: Complex multi-criteria search dialogs
+
+**Current Status**: ✅ Good search exists, but could be enhanced
+
+**Potential Improvements**:
+
+#### 9.1 Advanced Search Features
+- [ ] Saved search templates
+- [ ] Complex boolean search operators
+- [ ] Search history and favorites
+- [ ] Export search results to various formats
+
+#### 9.2 Search Performance
+- [ ] Search result caching
+- [ ] Async search for large datasets
+- [ ] Search analytics and optimization
+- [ ] Full-text search across documents
+
+---
+
+## SYSTEM ARCHITECTURE IMPROVEMENTS
+
+### 🔵 10. Workflow Engine
+
+**Legacy Feature**: Implicit workflow through business rules
+
+**Current Status**: ❌ Not implemented
+
+**Potential Implementation**:
+
+#### 10.1 Workflow Definition
+- [ ] Create workflow definition system
+- [ ] State machine implementation
+- [ ] Conditional workflow paths
+- [ ] Workflow versioning
+
+#### 10.2 Process Automation
+- [ ] Automatic task assignment
+- [ ] Email notifications and reminders
+- [ ] Document generation triggers
+- [ ] Status update automation
+
+### 🔵 11. Audit and Compliance
+
+**Legacy Feature**: Basic data integrity checks
+
+**Current Status**: ⚠️ Basic audit logging exists
+
+**Enhanced Features**:
+
+#### 11.1 Comprehensive Audit Trail
+- [ ] Detailed change tracking
+- [ ] User action logging
+- [ ] Data access monitoring
+- [ ] Compliance reporting
+
+#### 11.2 Legal Compliance
+- [ ] Client confidentiality controls
+- [ ] Data retention policies
+- [ ] Bar association compliance reporting
+- [ ] Trust account regulatory compliance
+
+### 🔵 12. Integration Platform
+
+**Legacy Feature**: WordPerfect and DOS integration
+
+**Current Status**: ❌ No external integrations
+
+**Modern Integrations**:
+
+#### 12.1 Office Suite Integration
+- [ ] Microsoft Office integration
+- [ ] Google Workspace integration
+- [ ] PDF generation and manipulation
+- [ ] Email integration (Outlook/Gmail)
+
+#### 12.2 Legal Software Integration
+- [ ] Court filing systems
+- [ ] Legal research platforms (Westlaw/Lexis)
+- [ ] Accounting software integration
+- [ ] Case management platforms
+
+---
+
+## IMPLEMENTATION ROADMAP
+
+### Phase 1: Core Business Features (3-6 months)
+1. Document Assembly System
+2. QDRO Module
+3. Advanced Billing & Statement Generation
+
+### Phase 2: Productivity Features (2-4 months)
+1. Integrated Time Tracking
+2. Enhanced File Management
+3. Advanced Printer Management
+
+### Phase 3: System Enhancements (2-3 months)
+1. Calendar/Appointment System
+2. Enhanced Lookup Management
+3. Workflow Engine
+
+### Phase 4: Integration and Compliance (1-2 months)
+1. Audit and Compliance
+2. Integration Platform
+3. Performance Optimization
+
+---
+
+## TECHNICAL CONSIDERATIONS
+
+### Database Schema Changes Required
+- New tables: `document_templates`, `template_keywords`, `qdros`, `plan_info`, `timers`, `workflows`
+- Extended tables: Enhanced `financial_transactions`, `files`, `customers`
+- Audit tables: Comprehensive change tracking
+
+### API Architecture Extensions
+- Document generation microservice
+- Timer/time tracking service
+- Workflow engine service
+- Notification service
+
+### Frontend Architecture
+- Document preview components
+- Timer widgets
+- Advanced form builders
+- Report generation interfaces
+
+### Infrastructure Requirements
+- Document storage (S3/MinIO)
+- Background job processing (Celery/RQ)
+- Real-time updates (WebSocket)
+- Print server integration (if required)
+
+---
+
+## SUCCESS METRICS
+
+### Business Impact
+- [ ] Reduction in document preparation time
+- [ ] Improved billing accuracy and speed
+- [ ] Enhanced client service delivery
+- [ ] Compliance with legal practice standards
+
+### Technical Performance
+- [ ] Document generation time < 5 seconds
+- [ ] Search response time < 500ms
+- [ ] 99.9% system uptime
+- [ ] Zero data loss incidents
+
+### User Adoption
+- [ ] 100% user migration from legacy system
+- [ ] Reduced training time for new users
+- [ ] Positive user satisfaction scores
+- [ ] Increased productivity metrics
+
+---
+
+## ESTIMATED EFFORT
+
+### Development Time (Person-Months)
+- **High Priority Features**: 8-12 months
+- **Medium Priority Features**: 4-6 months  
+- **Low Priority Features**: 3-4 months
+- **System Architecture**: 2-3 months
+
+### **Total Estimated Effort**: 17-25 person-months
+
+### Team Recommendations
+- 1 Full-stack Developer (lead)
+- 1 Backend Developer (APIs/database)
+- 1 Frontend Developer (UI/UX)
+- 1 DevOps Engineer (part-time)
+- 1 Legal Domain Expert (consultant)
+
+---
+
+*This TODO list should be regularly updated as features are implemented and new requirements are discovered.*
--- a/docs/README.md
+++ b/docs/README.md
@@ -230,6 +230,101 @@ Allowed sort fields (high level):
 - `PUT /api/documents/qdros/{file_no}/{id}` - Update QDRO
 - `DELETE /api/documents/qdros/{file_no}/{id}` - Delete QDRO

+📚 See also: [PENSIONS.md](PENSIONS.md) for detailed pensions API fields, sorting, and examples.
+
+### Pensions
+- `GET /api/pensions/schedules` - List pension schedules for a file
+  - Query params: `file_no` (required), `skip`, `limit`, `sort_by` (id,file_no,version,vests_on,vests_at), `sort_dir`, `include_total`,
+    filters: `start`, `end`, `version`, numeric ranges: `vests_at_min`, `vests_at_max`, search: `search` (tokenized across `version`, `frequency`).
+  - Examples:
+    ```bash
+    curl "http://localhost:6920/api/pensions/schedules?file_no=F-1&sort_by=vests_on&sort_dir=asc&limit=20&include_total=true"
+    curl "http://localhost:6920/api/pensions/schedules?file_no=F-1&version=02&vests_at_min=10&vests_at_max=50"
+    ```
+- `GET /api/pensions/marriages` - List marriage history for a file
+  - Query params: `file_no` (required), `skip`, `limit`, `sort_by` (id,file_no,version,married_from,married_to,marital_percent,service_from,service_to), `sort_dir`, `include_total`,
+    filters: `start`, `end`, `version`, numeric ranges: `married_years_min/_max`, `service_years_min/_max`, `marital_percent_min/_max`, search: `search` (tokenized across `version`, `spouse_name`, `notes`).
+  - Example:
+    ```bash
+    curl "http://localhost:6920/api/pensions/marriages?file_no=F-1&search=Jane%20Doe&sort_by=married_from&sort_dir=desc"
+    ```
+- `GET /api/pensions/death-benefits` - List death benefits for a file
+  - Query params: `file_no` (required), `skip`, `limit`, `sort_by` (id,file_no,version,lump1,lump2,growth1,growth2,disc1,disc2,created), `sort_dir`, `include_total`,
+    filters: `start`, `end`, `version`, numeric ranges: `lump1_min/_max`, `lump2_min/_max`, `growth1_min/_max`, `growth2_min/_max`, `disc1_min/_max`, `disc2_min/_max`, search: `search` (tokenized across `version`, `beneficiary_name`, `benefit_type`, `notes`).
+  - Example:
+    ```bash
+    curl "http://localhost:6920/api/pensions/death-benefits?file_no=F-1&lump1_min=100&sort_by=lump1&sort_dir=desc"
+    ```
+- `GET /api/pensions/separations` - List separation agreements for a file
+  - Query params: `file_no` (required), `skip`, `limit`, `sort_by` (id,file_no,version,agreement_date), `sort_dir`, `include_total`,
+    filters: `start`, `end`, `version`, search: `search` (tokenized across `version`, `terms`, `notes`).
+  - Example:
+    ```bash
+    curl "http://localhost:6920/api/pensions/separations?file_no=F-1&start=2024-01-01&end=2024-12-31&sort_by=agreement_date"
+    ```
+- `GET /api/pensions/{file_no}/detail` - Detail view for a file's pension data with nested, independently paginated lists
+  - Each nested list accepts its own paging/sorting/filtering query prefixes: `s_*` (schedules), `m_*` (marriages), `d_*` (death benefits), `sep_*` (separations)
+  - Example:
+    ```bash
+    curl "http://localhost:6920/api/pensions/F-1/detail?s_sort_by=vests_on&s_limit=10&m_sort_by=married_from&d_sort_by=lump1&sep_sort_by=agreement_date"
+    ```
+- `POST /api/pensions/` - Create a main Pension record
+  - Body (JSON, selected fields):
+    ```json
+    {
+      "file_no": "F-1",
+      "version": "01",
+      "plan_id": "PID1",
+      "plan_name": "Plan A",
+      "vested_per": 50,
+      "tax_rate": 25
+    }
+    ```
+  - Notes: numeric validation enforced (e.g., `vested_per` 0–100; `tax_rate` 0–100; monetary values non-negative)
+- `GET /api/pensions/{pension_id}` - Get a Pension by id
+- `PUT /api/pensions/{pension_id}` - Update a Pension (partial fields accepted)
+  - Example:
+    ```bash
+    curl -X PUT "http://localhost:6920/api/pensions/123" -H 'Content-Type: application/json' -d '{"plan_name":"Plan B","vested_per":75}'
+    ```
+- `DELETE /api/pensions/{pension_id}` - Delete a Pension
+
+### Templates
+- `GET /api/templates/search` - Search document templates
+  - Query params:
+    - `q` (str, optional): partial match on template name or description
+    - `category` (str[] or CSV, optional): filter by one or more categories. Repeat the parameter (`?category=A&category=B`) or pass a comma-separated list (`?category=A,B`).
+    - `keywords` (str[], optional, repeatable): keyword tags assigned to templates
+    - `keywords_mode` (str, optional): `any` (default) returns templates that match any of the provided keywords; `all` returns only templates that contain all the provided keywords
+    - `has_keywords` (bool, optional): when `true`, only templates that have one or more keywords are returned; when `false`, only templates with no keywords are returned
+    - `skip` (int, optional): pagination offset, default 0
+    - `limit` (int, optional): page size, default 50, max 200
+    - `sort_by` (str, optional): `name` (default) | `category` | `updated`
+    - `sort_dir` (str, optional): `asc` (default) | `desc`
+    - `active_only` (bool, optional): when `true` (default), only active templates are returned
+  - Examples:
+    ```bash
+    # Any of the keywords (default)
+    curl "http://localhost:6920/api/templates/search?keywords=qdro&keywords=divorce"
+
+    # Must contain all keywords
+    curl "http://localhost:6920/api/templates/search?keywords=qdro&keywords=divorce&keywords_mode=all"
+
+    # Sorted by name descending with pagination
+    curl "http://localhost:6920/api/templates/search?sort_by=name&sort_dir=desc&skip=10&limit=10"
+
+    # Include inactive templates
+    curl "http://localhost:6920/api/templates/search?active_only=false"
+    ```
+
+- `GET /api/templates/categories` - List distinct template categories with counts
+  - Query params:
+    - `active_only` (bool, optional): when `true` (default), only counts active templates
+  - Example:
+    ```bash
+    curl "http://localhost:6920/api/templates/categories?active_only=false"
+    ```
+
 ### Support
 - `POST /api/support/tickets` - Create support ticket (public; auth optional)
 - `GET /api/support/tickets` - List tickets (admin; supports filters, search, pagination, sorting, `include_total`)