top of page

Building a Scalable API Layer for Web, Mobile & Legacy Systems

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.

Engineering-Driven-Project-Estimation.png

Project Information

 

Client:

Maurizio

 

Location:

Canada

 

Project duration:

3 -6 Months

 

Technologies used:

Nextjs, Nestjs

​

Website:

https://arcadiaacademyofmusic.com/

Why API-First?

 

API-First means treating APIs as the core product, not as an output of the backend.

 

Benefits

  • One backend powering Next.js Web, React Native mobile, internal tools, and future integrations

  • Enables parallel development (frontend & backend teams independent)

  • Cleaner separation between domain logic and presentation logic

  • Enables gradual modernization — key for legacy migration

  • Enforces consistency across the entire system

2. High-Level Architecture

​

Purpose of the architecture:

  • The NestJS API becomes the new entry point

  • Yii2 remains accessible behind internal routes during migration

  • Allows a strangler pattern modernization (gradual replacement)

High-Level-Architecture.png

3. Migration Strategy: Strangler + Proxy Bridge

Migration-Strategy-Strangler-Proxy-Bridge.png

Benefits:

​

No downtime

  • Yii2 features are replaced one module at a time

  • Clients remain unaffected

  • Zero disruption for students, parents, teachers, staff

 

​

4. Standardized API Response Structure

 

Instead of custom error formats, we moved toward Stripe-style consistency:

Stripe Philosophy

  • Predictable field names

  • Machine-parsable error codes

  • Clear human messages

 

Our structure (inspired by Stripe / Shopify)

Our-structure.png

Why this works well:

 

  • Cross-platform consistency

  • Predictable UI handling

  • Cleaner logs

  • Easier monitoring

  • Better developer experience

​

 

5. Sentry for Errors Instead of Manual Handling

Manager feedback: “Why not use Sentry for exception structure?”

✔️ Correct — Sentry became our unified exception pipeline

✔️ Sentry receives all 4xx/5xx errors automatically

✔️ No need for custom error infrastructure

Sentry-for-Errors-Instead-of-Manual-Handling.png

Benefits:

  • Aggregated production errors

  • Notifications & dashboards

  • Release tracking

  • Error grouping

  • Zero code duplication

​

​

6. Request Lifecycle in NestJS

  • This enforces:

  • Authentication

  • Authorization

  • Validation

  • Consistent responses

  • Observability (Sentry + logs)

 

 

7. Multi-Tenant Architecture with Location Context

Each request includes a :location parameter to isolate data:

Multi-Tenant-Architecture.png

Benefits:

  • School-level isolation

  • Straightforward scaling

  • Cleaner database access

 

 

8. REST API Design Standards

We follow clean, resource-based URLs:Consistent naming, predictable patterns, easy discovery.

REST-API-Design-Standards.png

9. Benefits to Web, Mobile & Integrations

A single API serves all clients — consistent, reliable, scalable.

Benefits-to-Web-Mobile-Integrations.png

10. How This Helps Yii2 → Modern Migration

 

Manager specifically asked:

“Can this help a team transitioning from Yii2?”

Absolutely — here’s how:

​

Before Migration

  • Yii2 is the entire backend

  • Frontend and mobile are coupled tightly to PHP

 

During Migration

  • NestJS API becomes the new public API

  • Yii2 remains available via internal proxy routes

  • New features are built only in NestJS

  • Old features gradually replaced

 

After Migration

  • Yii2 is fully removed

  • NestJS owns all domain logic

  • Frontend/mobile untouched the entire time

  • Clean separation of concerns

​

11. Final Results

✔️ Unified API powering web, mobile, partners

✔️ Future-proof multi-client architecture

✔️ Predictable API experience

✔️ Faster development velocity

✔️ Sentry-powered error pipeline

✔️ Simplified migration from legacy

✔️ Scalable module structure

✔️ Cleaner domain modeling

 

12.Key Takeaways

 

API-First is essential for long-term scalability

Strike a balance: fewer code samples, more diagrams

Use Sentry for errors, not custom exception treesAdopt Stripe-style error patternsApply the strangler fig pattern for legacy migrationMulti-tenancy simplifies scalingA unified API powers web, mobile & third-party integrations

bottom of page