Framework Refactoring

MIGRATION GUIDE INCLUDED

---

The Problem

Version 7.x had several architectural limitations that impacted scalability and deployment:

• Complex deployment requiring external servlet containers (Tomcat)

• Limited scalability with Long-based primary keys hindering distributed systems

• Scattered codebase with user and product management code dispersed across projects

• Inconsistent structure in templates, configurations, and entity schemas

---

The Solution

Version 8.0 introduces significant architectural improvements that make the SDK more concise, more straight-forward and allow more rapid feature customization at any level:

Simplified Deployment

• Migrated from WAR to JAR packaging with embedded servlet container

• Standalone execution with java -jar application.jar

• Faster startup and better containerization support

Enhanced Scalability

• UUID primary keys for all core entities (replacing Long/BIGINT)

• Improved support for distributed systems

• Backward compatibility through bigint_id columns

Consolidated Architecture

• Framework-level user and product management

• Unified entity document schema

• Standardized template locations and configuration structure

---

The How

SDK Perspective

This release includes massive framework improvements that require code migration from v7.x to v8.0. A comprehensive migration guide is provided with detailed instructions for:

• Updating packaging from WAR to JAR

• Migrating primary keys from Long to UUID

• Updating application entry point and configuration

• Consolidating user and product management code

• Database migration procedures

• Rollback procedures

⚠️ Critical: This is a breaking change release. All customizations require code updates to migrate from v7.x to v8.0. The migration includes database schema changes that are automatically applied via Flyway.

⚠️ Important: Plan for a maintenance window (recommended: 2-4 hours) for production deployment. Test thoroughly in a test environment before production migration.

---

Migration Guide

Prerequisites

• Backup database

• Verify PostgreSQL version ≥ 12 (required for gen_random_uuid())

• Check disk space (migration creates temporary tables)

• Document current state: integrations, API clients, scheduled jobs

Migration Steps

1. Update Dependencies - Update project dependencies to v8.0

2. Update Configuration - Create main.properties, update IDE configuration

3. Update Code - Migrate Long IDs to UUID, update entity references

4. Update Frontend/API Clients - Handle UUID strings instead of numbers

5. Test in Development - Verify all functionality locally

6. Test Migration in Test Environment - Complete migration dry run

7. Production Deployment - Execute migration with monitoring

8. Post-Migration - Monitor logs, performance, and user feedback

Post-Migration Verification

• Login functionality

• View existing entities

• Create new entities

• Update existing entities

• Reports generation

• Workflow execution

---

Related Documentation

Layer	Documentation	Description
Migration Guide	[Migration Guide will be provided by your prject manager]	Complete migration instructions