Phased Migration to a Next-Generation Architecture — Why We're Not Rewriting

MAPRISE today runs on a lightweight front-end stack. The simple structure got us to production and let us add features continuously, but as the service grows, we plan a phased migration toward a more maintainable next-generation architecture.

This post is an engineer-perspective writeup of why we picked phased replacement over a rewrite, and the order in which we'll proceed. It's also a preview of design intent for the people who'll join us next.

Note: the base framework itself (Next.js) isn't something we need to keep under wraps, but the specific combination of surrounding libraries and implementation details we build on top of it are part of the product's competitive value, so for now we share only the conceptual selection direction.

Why phased replacement

Phased replacement keeps the old system running while progressively replacing it from the periphery. Compared to a rewrite, the key advantages:

1. The production service stays up — replace one feature at a time, with the ability to fall back to either side at any moment
2. Small, frequent releases — quality is higher with 1-2 week mini-releases than a months-long big-bang
3. Learnings stay actionable — knowledge gained during migration flows immediately into the next slice
4. Fits early-stage resource constraints — suits stages where blocking out a focused full-rewrite period is hard

MAPRISE has already established the "self-contained module pattern" inside the existing codebase. Recently added modules each have high independence and minimal global state exposure. That becomes the foundation for phased migration.

Selection direction (conceptual)

We're not naming the specific combination of surrounding libraries, but the selection direction is:

Common criteria across choices: no commercial license required, the recent major version is industry-standard adoption, maintainable by a small early-stage team.

Migration stages

The core of the migration strategy is "in what order to proceed." MAPRISE plan:

Stage 1: Foundations

• Set up the monorepo structure
• Add boundary tests for existing functionality
• Set up the type system

Stage 2: Replace peripheral UI

The landing side is already running on the new architecture. On the app side too, we replace peripheral UI in stages while keeping the map core on the current stack. Start with low-risk areas — an essential rule.

Stage 3: Map core separation

Reimplement the split-screen sync core, structure the layer catalog, and integrate the map library. The highest-risk segment, where the tests prepared in Stage 1 pay off.

Stage 4: AI chat replacement

Restructure the AI chat UI, streaming response handling, session restoration, and history navigation.

Stage 5: Remove old code

Delete the legacy files; the new architecture fully replaces them. Tighten the type system and complete final documentation.

Expected outcomes

Known risks and mitigations

1. Memory leaks: tighter cleanup discipline around map canvas re-mounting
2. Sync infinite loops: adopt a pattern that guarantees referential equality in split-screen state sync
3. Bundle size bloat: mandatory bundle analysis when adding packages
4. SEO regression: reuse patterns already proven elsewhere

Summary

MAPRISE's architecture migration is a phased replacement strategy that "minimizes risk while reliably retiring technical debt." We designed it to satisfy executability under a small-team + AI-assisted operation, founder equity protection, and ease of new-member onboarding — all simultaneously.

Until then, we keep iterating on the current stack for PMF validation and customer acquisition.

For engineering inquiries, design discussions, or improvement proposals: info@maprise.jp.

In parallel, see the event post "Yokatoko bizcon application" also published today (5/24).