What I Learned Rebuilding a Legacy Liferay Portal with React and REST APIs
The starting point was a meeting and governance portal built on Liferay 6.2: meetings, subjects, agendas, attendance and decisions, all rendered through JSP-based portlets, all deeply familiar to the people who used it every day. It was unsupportable, could not integrate with modern calendaring, and nobody wanted to change a line of it.
The output was a rebuilt portal on current Liferay with a React front end talking to REST APIs, a unified calendar, in-portal conference scheduling, and two-way synchronisation with an external calendar. What follows is what I would tell a team about to start the same journey.
Say the word rebuild out loud, early
The gap between 6.2 and current Liferay is not a version gap, it is an architectural one. The portlet model, the module system, the front-end stack and the API surface all changed. Calling the project an upgrade sets an expectation of continuity that the work cannot deliver, and every subsequent estimate gets measured against that wrong baseline.
This is the exception to a rule I otherwise argue for. Most legacy customizations are better modernized incrementally than rewritten, and incremental migration should always be the first option examined. It stops being available when the platform boundary itself moves, which is exactly what happens across this particular version gap. Naming the project a rebuild also makes the move to a modular architecture a deliberate design decision rather than an unpleasant surprise, and gives the team permission to redesign the parts that were only shaped that way because of 6.2 constraints.
The legacy system is the specification, and it is undocumented
There was no complete written specification, which is normal. The real specification was distributed across the code, the database, and the habits of the people using it. Reading the old JSPs told us what the screens did; it did not tell us which behaviours mattered.
Three sources together produced a usable specification. The code told us what was possible. The production data told us what was actually used - including several features with no usage at all in three years. And sitting with users told us which quirks were load-bearing, because some of what looked like an accident of the old interface had become part of how the organisation worked.
Dropping unused features was the single largest scope reduction available, and it was only possible because we looked at the data before committing to parity.
Define parity in workflows, not features
A feature list is a poor definition of done for a rebuild, because it hides the sequences. Users do not use features, they complete tasks: schedule the meeting, attach the subjects, circulate the agenda, record attendance, publish decisions.
Writing parity as a list of workflows exposed things a feature list missed - one report that was always exported immediately after a specific action, a permission that mattered only in the gap between two steps, a screen that was never used except on the day of a meeting. It also made acceptance concrete: the test was whether a user could complete the workflow without being told anything new.
The API boundary was the real design work
The genuinely architectural decisions were not about React. They were about resource granularity - what a meeting is, whether subjects belong to the meeting or exist independently, whether attendance is a sub-resource or its own entity.
| Modelling choice | Consequence in the front end |
|---|---|
| Subjects nested under a meeting | Simple meeting screen; painful to reuse a subject across meetings |
| Subjects as their own resource with a link | One more call per screen; supports carry-forward and history |
| Attendance as a sub-resource | Natural for the attendance screen; awkward for reporting |
| Decisions as records referencing a subject | Extra work up front; made the decision history feature possible |
The lesson that generalises is that the API shape sets the ceiling on how simple the front end can be. When a screen needed three calls and client-side stitching, the model was usually wrong rather than the screen. It is the same discipline required when the backend is generated from a data model: design the resources against the screens you know you need.
Calendars are harder than the estimate
A unified calendar surfacing meetings and related items in one view sounds like a display feature. It is not. Calendar work carries a set of problems that all arrive together.
- Recurrence: an edit applies to one occurrence, the rest of the series, or all of it - and users expect to be asked.
- Time zones: storing an instant is easy; deciding whether a rescheduled meeting keeps local time or absolute time is a business question.
- All-day versus timed entries, which behave differently at boundaries and in every external system.
- A single view over several entity types, each with its own permissions, where a user may see one item and not another.
The fourth point was the one that cost the most. Rendering a mixed-type calendar means the query has to apply different authorisation rules per item type while still paging sensibly, and none of that is visible in the mock-up that got approved.
Two-way sync is a distributed systems problem
Synchronising with an external calendar was requested as an integration and turned out to be the most technically demanding part of the project. The moment two systems can both change the same thing, you are in distributed systems territory whether you planned to be or not.
- Decide the system of record per field, and write it down. Ours owned the agenda; the external calendar owned nothing authoritative but could still be edited.
- Make every sync operation idempotent, keyed by a stable external identifier, so a replay never duplicates an event.
- Define conflict resolution explicitly - last write wins is a choice, not a default, and it needs to be a stated one.
- Treat token refresh and revocation as first-class flows; access is revoked by users at unpredictable times.
- Log every sync attempt with its outcome. Without this, the first support question is unanswerable.
- Build a reconciliation view that lists items out of sync, because they will exist.
If I were scoping this again, I would size two-way sync as its own workstream rather than a line item under integrations, and I would ship one-way sync first to learn the failure modes cheaply.
Data migration is the long pole
Rebuilding the application was predictable work. Moving years of meetings, subjects, attachments and decisions was not. Legacy identifiers appeared in places we did not expect, attachments referenced a storage layout that no longer existed, and historical records contained combinations of values that the new validation rules rejected.
The decision that saved us was to treat the migration as its own deliverable with its own tests - run repeatedly against a copy of production, with a reconciliation report comparing counts and spot-checked records. The alternative, migrating once during the cutover weekend, is how these projects end up rolling back.
The other useful decision was agreeing early what would not be migrated. Not every historical record needed to be live in the new system; some were better served by a read-only archive, which removed a large amount of transformation work for data nobody would open.
React inside a portal has its own questions
Choosing React was uncontroversial. Deciding where it lives was not, and the questions were practical: how routing behaves when the application sits inside a portal page, how the session is shared and what happens when it expires mid-form, and how much of the portal shell the application should reuse rather than reimplement.
Session expiry deserves specific attention, because it is invisible during development and obvious the first week in production. A user with a long-open form must be told clearly rather than losing their work to a silent failed request. Deciding these questions up front also determines how independently the front end can be deployed, which is exactly the trade-off that client extensions were designed to resolve.
What I would do differently
- Freeze the legacy system earlier. Changes made to it during the rebuild had to be implemented twice, and each one arrived as a surprise.
- Build the read-only views first and put them in front of users, where they validate the data model far earlier than editable screens do.
- Invest in a realistic seeded dataset in week one; demos on three fabricated meetings hide every problem that appears at scale.
- Ship one-way calendar sync before attempting two-way, to learn the integration's failure modes under low stakes.
- Write the parity checklist as workflows before any estimate is given, rather than reconstructing it halfway through.
Conclusion
The framework choice was the least interesting decision in the project. What determined the outcome was treating it honestly as a rebuild, deriving the specification from behaviour and real usage rather than from legacy code, designing the API boundary against the screens it had to serve, and respecting that calendars, synchronisation and data migration are each harder than they look. Users measured success by whether their workflows still worked on the first Monday. Everything else was implementation detail.