Legacy Migration
One NestJS API Layer for Web, Mobile, and Legacy: SMW Music Academy
Migrating SMW Music Academy from a monolithic Yii2 PHP backend to a modern stack was more than a rewrite - it was a strategic modernization initiative. The core principle behind this transformation was an API-First Architecture, enabling us to power web, mobile, partner integrations, and future products with a single, scalable API layer. This version focuses on architecture, transition patterns, and system flows instead of code - with visuals and diagrams for clarity.
Project Overview
SMW Music Academy's monolithic Yii2 PHP backend served only server-rendered web pages, with no support for mobile apps or partner integrations. We designed and implemented an API-First architecture using NestJS, applying the Strangler Fig pattern to replace legacy modules one at a time with zero downtime. The result is a single, unified API layer that powers web, mobile, and third-party consumers, with Stripe-style response consistency, Sentry-powered error monitoring, and multi-tenant data isolation across school locations.
High-Level Architecture
The API layer is structured as a single NestJS service acting as the unified entry point for all client types, web, mobile, partner integrations, and internal tools. All requests flow through a shared authentication and authorization layer before reaching the appropriate module, ensuring consistent security and response handling across every consumer.
Migration Strategy: Strangler Fig + Proxy Bridge
Rather than a full rewrite, NestJS was introduced as a proxy bridge in front of the existing Yii2 backend. New modules were built directly in NestJS while legacy routes were transparently forwarded to Yii2 through internal routing, allowing both systems to run in parallel with zero downtime throughout the migration.
Project Structure & Module Organization
A clean, domain-driven module structure ensures each feature area is independently maintainable. Every module owns its controllers, services, repositories, and DTOs, eliminating the cross-concern coupling that made the legacy monolith difficult to extend.
Unified Error Handling with Sentry
Instead of scattered custom error formats across endpoints, all exceptions route through a single Sentry pipeline. Every 4xx and 5xx error is captured with full context (stack trace, request data, user session), making debugging fast and consistent regardless of which module triggers the error.
Multi-Tenant Architecture
The academy operates across multiple locations, each requiring strict data isolation. The multi-tenant design enforces per-request location context, ensuring no data from one school is ever accessible to another, without requiring separate deployments or databases.
REST API Design Standards
All endpoints follow clean, resource-based URL conventions with Stripe-style response envelopes, predictable field names, machine-parsable error codes, and consistent pagination. This makes the API self-documenting and reduces client integration time across all consumer types.
Business Benefits: Web, Mobile & Integration Ready
The API-First approach unlocks value far beyond the initial web migration. A single consistent API now powers the web platform, enables mobile app development without backend changes, and provides a stable integration surface for future partner systems.
Client Objectives
The engagement was guided by clear objectives that defined success for business leadership and delivery teams.
Build a Unified API Layer
Create a single NestJS API that powers web, mobile, internal tools, and future partner integrations.
Enable Gradual Migration
Use the Strangler Fig pattern to replace Yii2 modules one at a time with zero downtime.
Standardize API Responses
Adopt Stripe-style consistent response formats across all endpoints for predictable client handling.
The challenge
Complex constraints hindering growth
Monolithic Backend
The legacy Yii2 PHP backend tightly coupled frontend and backend logic, making it impossible to serve multiple client types from a single API.
No Mobile or Partner API
The existing system could only serve server-rendered web pages: no support for mobile apps, partner integrations, or third-party consumers.
Inconsistent Error Handling
Custom error formats varied across endpoints, making debugging difficult and creating unpredictable behavior for frontend developers.
Multi-Location Data Isolation
The academy operated across multiple locations, but the backend lacked proper tenant isolation, risking data leakage between schools.
The solution
API-First Modernization
A strategic migration treating APIs as the core product, enabling parallel development and gradual Yii2 replacement.
API-First Architecture
Established NestJS as the new API entry point, treating APIs as the core product rather than a backend output. This enabled parallel frontend and backend development.
- API-First
- NestJS
- Decoupling
Strangler + Proxy Bridge
Implemented a proxy bridge so the NestJS API became the public-facing layer while Yii2 remained accessible via internal routes. Features were replaced one module at a time.
- Strangler Fig
- Proxy Bridge
- Zero Downtime
Standardized API Responses & Sentry Pipeline
Adopted Stripe/Shopify-style response formats with predictable field names and machine-parsable error codes. Integrated Sentry as the unified exception pipeline for all 4xx/5xx errors.
- Stripe-Style API
- Sentry
- Error Monitoring
Multi-Tenant Architecture & REST Standards
Built location-based multi-tenancy with per-request data isolation. Enforced clean, resource-based REST URL conventions for consistent API discovery.
- Multi-Tenant
- REST Standards
- Data Isolation
Technologies Implemented
- Next.js
- NestJS
- Sentry
- MySQL
- 1
- Unified API for All Clients
- 0
- Downtime During Migration
- 3+
- Client Types Served (Web, Mobile, Partners)
- 3-6 mo
- Migration Timeline
Business impact
Architecture-Level Business Impact
The API-First approach transformed a single-purpose backend into a scalable, multi-client platform.
Cost Efficiency
- 1 API
- Serves all clients instead of separate backends
- Lower
- Ongoing maintenance with modular architecture
Development Velocity
- Faster
- Feature delivery with parallel development
- Automated
- Error monitoring via Sentry pipeline
Future-Ready Platform
- Mobile
- App-ready API from day one
- Scalable
- Multi-tenant architecture for new locations
How we drive results
Turning Strategy into Measurable Business Impact
Our case studies reflect a consistent delivery model focused on outcomes, helping organizations modernize technology, reduce risk, and accelerate growth through practical, scalable solutions.
Outcome-Driven Strategy
Every engagement starts with clear business objectives, success metrics, and a roadmap aligned to real operational and financial outcomes.
Proven Execution Model
We apply proven frameworks, agile delivery, and industry best practices to execute complex initiatives with speed, quality, and predictability.
Secure & Scalable Delivery
Our solutions are built with security, compliance, and scalability at the core, ensuring long-term resilience and sustainable growth.
Ready to Build a Unified API Layer?
From monolithic backends to API-First architecture, let us build a single, scalable API that powers your web, mobile, and partner integrations.
Start Your API Migration