stupa-pdf-api/CHANGES.md

Changes Summary - Dynamic Application System

Overview

The application system has been completely redesigned to be fully dynamic and configurable. All application types, fields, statuses, and workflows are now defined in the database rather than hardcoded.

Major Changes

1. Database Architecture

New Tables

• application_types - Defines application type templates
• application_fields - Field definitions for each type
• application_type_statuses - Status definitions per type
• status_transitions - Workflow transition rules
• dynamic_applications - Application instances
• application_history_v2 - Complete audit trail
• application_attachments_v2 - File attachments
• application_transition_logs - Status change tracking
• application_approvals - Approval decisions

Removed Tables

• applications (old fixed structure)
• form_templates (replaced by application_types)
• field_mappings (integrated into application_fields)

2. Core Features

Dynamic Field System

• 18+ field types (text, date, amount, etc.)
• Conditional display rules
• Custom validation per field
• Section grouping
• Default values and placeholders

Flexible Workflow

• Custom statuses with colors/icons
• Configurable transitions between statuses
• Multiple trigger types:
  • User approval (with role requirements)
  • Applicant actions
  • Time-based triggers
  • Condition-based triggers
  • Automatic transitions

Enhanced Cost Management

• Up to 100 cost positions (previously 24)
• Up to 100 comparison offers (previously 24)
• Categories and notes per position
• Automatic total calculation

3. API Changes

New Endpoints

Application Types:

• GET /api/application-types - List all types
• GET /api/application-types/{id} - Get specific type
• POST /api/application-types - Create new type (admin)
• PUT /api/application-types/{id} - Update type (admin)
• DELETE /api/application-types/{id} - Delete/deactivate type
• POST /api/application-types/{id}/pdf-template - Upload PDF

Dynamic Applications:

• GET /api/applications - List with advanced filtering
• GET /api/applications/{id} - Get with access key support
• POST /api/applications - Create with type selection
• PUT /api/applications/{id} - Update with validation
• POST /api/applications/{id}/submit - Submit for review
• POST /api/applications/{id}/transition - Status change
• POST /api/applications/{id}/approve - Approval actions
• GET /api/applications/{id}/history - Audit trail
• POST /api/applications/{id}/generate-pdf - PDF generation

Removed Endpoints

• All QSM/VSM specific endpoints
• Fixed form template endpoints
• Legacy PDF processing endpoints

4. Models & Types

New TypeScript Types (frontend/src/types/dynamic.ts)

• ApplicationType - Type definition
• FieldDefinition - Field configuration
• StatusDefinition - Status configuration
• TransitionDefinition - Workflow rules
• DynamicApplication - Application instance
• CostPosition - Cost item structure
• ComparisonOffer - Vendor offer structure

New Python Models (backend/src/models/application_type.py)

• ApplicationType - Type ORM model
• ApplicationField - Field ORM model
• ApplicationTypeStatus - Status ORM model
• StatusTransition - Transition ORM model
• DynamicApplication - Application ORM model
• Supporting models for history, attachments, approvals

5. Services

New Services

• NotificationService - Email notifications with templates
• PDFService - Dynamic PDF generation
• AuthService - Enhanced authentication with roles

Enhanced Services

• Field validation with type-specific rules
• PDF template mapping and filling
• Workflow engine for transitions
• Audit logging for all changes

6. Frontend Updates

New Components (to be implemented)

• Dynamic field renderer
• Visual workflow designer
• Application type builder
• Status badge with colors
• Cost position manager (100 items)
• Comparison offer manager (100 items)

API Client (frontend/src/api/dynamicClient.ts)

• Full TypeScript support
• Automatic token refresh
• Public access support
• Error handling
• File upload support

7. Migration

Data Migration (backend/scripts/migrate_to_dynamic.py)

• Creates QSM and VSM as dynamic types
• Migrates existing applications
• Preserves all data and relationships
• Maintains audit trail

Migration Steps

1. Run database migration to create new tables
2. Execute migration script to create default types
3. Verify data integrity
4. Update frontend to use new endpoints
5. Remove old code and tables

8. Configuration

Environment Variables

# New/Updated
MAX_COST_POSITIONS=100
MAX_COMPARISON_OFFERS=100
PDF_TEMPLATE_STORAGE=database
DYNAMIC_FIELD_VALIDATION=true
WORKFLOW_ENGINE_ENABLED=true
AUDIT_LOGGING_LEVEL=detailed

9. Benefits

For Administrators

• Create new application types without coding
• Visual workflow designer
• Flexible field configuration
• PDF template management
• Role-based access control

For Users

• Consistent interface across all types
• Better validation and help text
• Public access with keys
• Enhanced cost management
• Real-time status tracking

For Developers

• No hardcoded logic
• Extensible field types
• Clean separation of concerns
• Full TypeScript support
• Comprehensive audit trail

10. Breaking Changes

Backend

• All application endpoints changed
• Database schema completely redesigned
• Old models removed
• API response format changed

Frontend

• New type system required
• API client rewritten
• Component props changed
• State management updated

11. Upgrade Path

1. Backup all existing data
2. Deploy new backend with migrations
3. Run migration script
4. Update frontend to new API
5. Test thoroughly
6. Remove old code and tables

12. Future Enhancements

• Form templates and presets
• Batch operations
• Advanced reporting
• Mobile app support
• Webhook integrations
• Custom field types via plugins
• Multi-language support
• Advanced PDF templates with conditionals

Summary

This update transforms the application system from a fixed, hardcoded structure to a fully dynamic, database-driven system. While this is a major breaking change, it provides unlimited flexibility for future requirements without code changes.