stupa-pdf-api/DYNAMIC_SYSTEM_ARCHITECTURE.md

# Dynamic Application System Architecture

## Overview

This document describes the new fully dynamic application system that replaces the previous fixed QSM/VSM structure. The system now allows administrators to define any type of application with custom fields, statuses, and workflows.

## Core Concepts

### 1. Application Types

Application types are fully configurable templates that define:
- **Fields**: Dynamic field definitions with types, validation, and display rules
- **Statuses**: Custom status workflow with transitions
- **PDF Templates**: Optional PDF template with field mapping
- **Access Control**: Role-based access restrictions
- **Limits**: Maximum cost positions and comparison offers

### 2. Fields

Fields are the building blocks of applications with the following types:
- `text_short`: Short text input (max 255 chars)
- `text_long`: Long text/textarea
- `options`: Single selection from predefined options
- `yesno`: Boolean yes/no field
- `mail`: Email address with validation
- `date`: Date picker
- `datetime`: Date and time picker
- `amount`: Numeric amount field
- `currency_eur`: EUR currency field with formatting
- `number`: General numeric field
- `file`: File upload
- `signature`: Digital signature field
- `phone`: Phone number with validation
- `url`: URL with validation
- `checkbox`: Single checkbox
- `radio`: Radio button group
- `select`: Dropdown selection
- `multiselect`: Multiple selection

Each field supports:
- **Validation Rules**: min/max values, patterns, required status
- **Display Conditions**: Show/hide based on other field values
- **Default Values**: Pre-filled values
- **Placeholders & Help Text**: User guidance

### 3. Status System

Statuses define the workflow states:
- **Editability**: Whether the application can be edited
- **Visual Style**: Color and icon for UI
- **Notifications**: Email templates for status changes
- **Transitions**: Rules for moving between statuses

### 4. Transitions

Transitions define how applications move between statuses:

**Trigger Types:**
- `user_approval`: Requires N users with specific role to approve
- `applicant_action`: Button/action by the applicant
- `deadline_expired`: Automatic when a deadline passes
- `time_elapsed`: After a specific time period
- `condition_met`: When field conditions are satisfied
- `automatic`: Immediate automatic transition

## Database Schema

### Core Tables

1. **application_types**
   - Defines application type templates
   - Stores PDF template as BLOB
   - Contains field mapping configuration

2. **application_fields**
   - Field definitions for each type
   - Validation rules as JSON
   - Display conditions as JSON

3. **application_type_statuses**
   - Status definitions per type
   - Visual configuration (color, icon)
   - Notification templates

4. **status_transitions**
   - Transition rules between statuses
   - Trigger configuration
   - Conditions and actions

5. **dynamic_applications**
   - Actual application instances
   - Common fields (email, title, names)
   - Dynamic field_data as JSON
   - Cost positions and comparison offers as JSON

6. **application_history_v2**
   - Complete audit trail
   - Field-level change tracking
   - User and IP tracking

7. **application_approvals**
   - Approval decisions by role
   - Comments and timestamps

## API Endpoints

### Application Types Management

```
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 type (admin)
POST   /api/application-types/{id}/pdf-template - Upload PDF template
```

### Dynamic Applications

```
GET    /api/applications                - List applications
GET    /api/applications/{id}           - Get application details
POST   /api/applications                - Create new application
PUT    /api/applications/{id}           - Update application
POST   /api/applications/{id}/submit    - Submit for review
POST   /api/applications/{id}/transition - Change status (admin)
POST   /api/applications/{id}/approve   - Approve/reject
GET    /api/applications/{id}/history   - Get history
POST   /api/applications/{id}/generate-pdf - Generate PDF
```

## Common Fields

The following fields are always present (not dynamic):

1. **Email**: Applicant's email address
2. **Status**: Current workflow status
3. **Type**: Application type reference
4. **Title**: Application title/subject
5. **First Name**: Applicant's first name
6. **Last Name**: Applicant's last name
7. **Timestamps**: Created, submitted, status changed, completed
8. **Cost Positions**: Up to 100 items with description, amount, category
9. **Comparison Offers**: Up to 100 vendor offers

## Frontend Components

### Dynamic Field Renderer

The frontend includes a dynamic field rendering system that:
- Renders fields based on type
- Applies validation rules
- Handles display conditions
- Manages field dependencies

### Status Workflow UI

Visual workflow display showing:
- Current status with color/icon
- Available actions
- Transition history
- Approval tracking

### Admin Interface

Application type builder with:
- Drag-and-drop field designer
- Visual workflow editor
- PDF template mapper
- Role management

## Migration from Old System

### Data Migration Steps

1. **Create new tables** - Run migration script
2. **Define standard types** - Create QSM/VSM as dynamic types
3. **Map existing data** - Convert old applications to new format
4. **Update references** - Point to new tables
5. **Remove old tables** - Clean up after verification

### Field Mapping

Old QSM/VSM fields map to dynamic fields:

```json
{
  "project.name": "project_name",
  "applicant.name.first": "first_name",
  "applicant.name.last": "last_name",
  "applicant.contact.email": "email",
  "project.costs": "cost_positions",
  "project.totals.requestedAmountEur": "total_amount"
}
```

## Security & Access Control

### Role-Based Access

- **Admin**: Full access to type management and all applications
- **Budget Reviewer**: Review and approve budget-related applications
- **Finance Reviewer**: Financial review and approval
- **AStA Member**: Voting rights on applications
- **Applicant**: Create and edit own applications

### Public Access

Applications can be accessed via:
- **Authenticated**: Full access based on role
- **Access Key**: Limited access with unique key
- **Public Link**: Read-only access if configured

## Configuration

### Environment Variables

```env
# Database
DATABASE_URL=mysql://user:pass@localhost/stupa_db

# Email
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASSWORD=secret
FROM_EMAIL=noreply@example.com
FROM_NAME=Application System

# Security
JWT_SECRET_KEY=your-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Storage
PDF_OUTPUT_DIR=./uploads/pdfs
ATTACHMENT_DIR=./uploads/attachments
MAX_UPLOAD_SIZE=10485760

# Frontend
BASE_URL=https://applications.example.com
```

### Application Type Example

```json
{
  "type_id": "travel_grant",
  "name": "Travel Grant Application",
  "description": "Apply for travel funding",
  "fields": [
    {
      "field_id": "destination",
      "field_type": "text_short",
      "name": "Destination",
      "is_required": true,
      "validation_rules": {
        "max_length": 100
      }
    },
    {
      "field_id": "purpose",
      "field_type": "text_long",
      "name": "Purpose of Travel",
      "is_required": true,
      "validation_rules": {
        "min_length": 50,
        "max_length": 500
      }
    },
    {
      "field_id": "travel_date",
      "field_type": "date",
      "name": "Travel Date",
      "is_required": true,
      "validation_rules": {
        "min_date": "2024-01-01"
      }
    },
    {
      "field_id": "amount_requested",
      "field_type": "currency_eur",
      "name": "Amount Requested",
      "is_required": true,
      "validation_rules": {
        "min": 0,
        "max": 5000
      }
    }
  ],
  "statuses": [
    {
      "status_id": "draft",
      "name": "Draft",
      "is_editable": true,
      "color": "#6B7280",
      "is_initial": true
    },
    {
      "status_id": "submitted",
      "name": "Submitted",
      "is_editable": false,
      "color": "#3B82F6",
      "send_notification": true
    },
    {
      "status_id": "approved",
      "name": "Approved",
      "is_editable": false,
      "color": "#10B981",
      "is_final": true
    },
    {
      "status_id": "rejected",
      "name": "Rejected",
      "is_editable": false,
      "color": "#EF4444",
      "is_final": true
    }
  ],
  "transitions": [
    {
      "from_status_id": "draft",
      "to_status_id": "submitted",
      "name": "Submit Application",
      "trigger_type": "applicant_action"
    },
    {
      "from_status_id": "submitted",
      "to_status_id": "approved",
      "name": "Approve",
      "trigger_type": "user_approval",
      "trigger_config": {
        "role": "admin",
        "required_approvals": 1
      }
    },
    {
      "from_status_id": "submitted",
      "to_status_id": "rejected",
      "name": "Reject",
      "trigger_type": "user_approval",
      "trigger_config": {
        "role": "admin",
        "required_approvals": 1
      }
    }
  ]
}
```

## Advantages of Dynamic System

1. **Flexibility**: Create any type of application without code changes
2. **Maintainability**: All configuration in database, no hardcoded logic
3. **Scalability**: Same infrastructure handles all application types
4. **User Experience**: Consistent interface across all applications
5. **Compliance**: Built-in audit trail and approval workflows
6. **Integration**: PDF generation works with any template
7. **Future-Proof**: Easy to add new field types and features

## Performance Considerations

- **JSON Fields**: Indexed for fast searching
- **Caching**: Application types cached in memory
- **Lazy Loading**: Field data loaded on demand
- **Batch Operations**: Support for bulk status changes
- **Async Processing**: PDF generation in background

## Backup and Recovery

- **Daily Backups**: Automated database backups
- **Version History**: All changes tracked in history tables
- **Soft Deletes**: Applications marked as deleted, not removed
- **Export/Import**: JSON format for data portability