Epic: Migrating to React Plan

[sayazian]

Us:
We have a java app with Spring on the backend and Thymeleaf on the frontend and we want to covert it to a react app with the data being accessed through Rest. How would we begin to write these tickets and how many tickets would it take? Should I create a feature tag? We have about 8 tables.

Codex:
Yes, create a feature tag / epic for this. I’d make one parent epic like:

feature: react-rest-migration

or, if your tracker supports epics:

Epic: Migrate Thymeleaf UI to React + REST API

Then break the work into tickets by migration layer, not only by table. With 8 tables, I’d expect roughly 12-20 tickets, depending on complexity, relationships, auth, validation, and how many screens exist.

Suggested Ticket Structure

1. Audit Existing Thymeleaf Screens

   • List all current pages, forms, tables, filters, actions, redirects, and backend controller methods.
   • Map each screen to the tables/entities it uses.

2. Define REST API Contract

   • Decide endpoint naming, request/response shapes, pagination, validation errors, auth behavior.
   • Example: /api/customers, /api/orders/{id}, etc.

3. Set Up React App

   • Choose build tooling, likely Vite.
   • Add routing, API client, environment config, basic layout.
   • Decide whether React lives inside the Spring app or as a separate frontend app.

4. Add Backend REST Layer

   • Create REST controllers alongside existing Thymeleaf controllers.
   • Reuse existing services where possible.
   • Avoid putting business logic directly in controllers.

5. Authentication / Session Handling

   • Decide whether to keep Spring Security sessions or move to token-based auth.
   • Add frontend handling for login, logout, unauthorized states.

6. Shared API Error Handling

   • Standardize validation errors and server errors.
   • Frontend should have reusable handling for form errors, toast messages, and redirects.

7. React Layout / Navigation

   • Replace common Thymeleaf layout fragments with React shell components.
   • Navigation, header, sidebar, footer, breadcrumbs, etc.

8. Entity Screen Migration Tickets
   For each major table/entity, create one ticket or split into list/detail/form if complex.

   Example:

   • Migrate Customers list/detail/edit screens to React
   • Migrate Orders list/detail/edit screens to React
   • Migrate Products list/detail/edit screens to React

   With 8 tables, this is likely 8-12 tickets.

9. Frontend Data Layer

   • Add API client helpers.
   • Consider React Query or SWR for fetching, caching, loading states, and mutations.

10. Validation Parity

• Ensure React forms enforce the same validation as backend.
• Backend remains source of truth.

11. Remove or Disable Thymeleaf Routes

• Once React screens are verified, remove old Thymeleaf templates/controllers or redirect old routes.

12. End-to-End Regression Testing

• Smoke test critical workflows.
• Add backend API tests and frontend integration tests where valuable.

Example Epic Breakdown

For 8 tables, a realistic first pass might be:

• 1 audit ticket
• 1 API contract ticket
• 1 React setup ticket
• 1 auth/session ticket
• 1 shared layout/navigation ticket
• 1 shared API/error-handling ticket
• 8 entity migration tickets
• 1 cleanup ticket
• 1 regression/testing ticket

That gives you about 16 tickets.

If the 8 tables are simple CRUD, you may get away with 10-12 tickets. If they have relationships, workflows, role permissions, reporting, uploads, or complex forms, expect closer to 18-25 tickets.

Recommendation

Create the feature tag/epic, then start with a discovery ticket before writing all implementation tickets in detail. The discovery ticket should produce a screen/API migration matrix. That matrix will tell you whether each table deserves one ticket or several.