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:

{
  "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

# 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

{
  "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