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.
Why API-First?
API-First means treating APIs as the core product, not as an output of the backend.
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
Project Information
Client:
Maurizio
Location:
Canada
Project duration:
3 -6 Months
Technologies used:
Nextjs, Nestjs
Website:
https://arcadiaacademyofmusic.com/
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)
3. Migration Strategy: Strangler + Proxy Bridge
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)
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
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:
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.
9. Benefits to Web, Mobile & Integrations
A single API serves all clients — consistent, reliable, scalable.
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 trees
Adopt Stripe-style error patterns
Apply the strangler fig pattern for legacy migration
Multi-tenancy simplifies scaling
A unified API powers web, mobile & third-party integrations
