Migrate a Monolith to Next.js and PostgreSQL

Big-bang rewrites are how products freeze. At Agentic Academy Labs we migrate monoliths (PHP, Rails, older Node) to Next.js and PostgreSQL with a strangler pattern: new UI on the App Router, Bun or Route Handlers for new APIs, old server still serving what has not moved, then data cutover with replication and checks. Flutter apps keep a stable HTTP contract while hosts change. This is the same discipline as our cloud migration checklist, applied to the application itself. Work is run from Sikar with the client's operators on the old box.

Strangler steps we follow

1. Inventory screens, APIs, jobs, uploads, and who owns each table. Interns are good at this pass.
2. Stand up Next.js plus PostgreSQL plus CI. Local Postgres first, hosted project second.
3. Move one high-value journey (login, pay, or the screen that generates support tickets).
4. Replicate or dual-write critical tables. Validate with checksums, not hope.
5. Point DNS and the Flutter base URL with a flag. Keep rollback for a named window.
6. Retire legacy routes only after smoke tests and a week of error budgets.

What week 1 contains

• A route map: URL, owner, traffic, and 'move / wrap / leave.'
• A restore of the current backup into a scratch Postgres. If restore fails, stop.
• Auth decision: session cookies on Next.js vs tokens the Flutter app already uses.
• SEO URL list if the monolith is public. 301s are a deliverable, not a follow-up.
• A written freeze policy: which features still land on the old stack during the strangler.

Data cutover without folklore

PostgreSQL is our default because transactional apps, reporting, and later pgvector for AI features share one operational skill. We do not rename every column for taste. We do add tenant_id and created_at where the monolith was sloppy. Dual-write is for tables that cannot freeze. Batch copy is for archives. Always compare row counts and a few business checksums (open orders, wallet sums) before calling it done. Data engineering joins when the monolith's 'reports' are actually a second system.

Risks and mitigations

Where AI fits (later)

Once the new app has Postgres and a clean API, adding RAG is the architecture in Next.js AI app architecture. Doing RAG inside the monolith's undocumented jobs is how citations rot. We have paused AI scope mid-migration when inventory showed three sources of customer truth. That pause saved the kind of corpus mess that otherwise lands in week 4 of an assistant project.

Failure modes from our migrations

• Rewriting the admin first because it is ugly. Users live in the customer journey; strangler that first.
• New Next.js app talking to the old MySQL with an ORM 'for now.' You just added a fourth runtime.
• No job inventory. Nightly invoices kept running on the old box against stale rows.
• Intern-built pages without the design system. UI/UX belongs in the landing zone, not as a polish sprint after cutover.

A focused product can move in months. A domain with years of reports takes longer. Discovery produces a phased plan; we do not quote a single weekend. Pair the work with web and mobile development and cloud migration when hosting moves at the same time. Agentic Academy Labs will schedule a call if you bring the route map, even a messy one.