> For the complete documentation index, see [llms.txt](https://docs.timvero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.timvero.com/release-log/release-notes-8.0/framework-refactoring.md).

# 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 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.timvero.com/release-log/release-notes-8.0/framework-refactoring.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.