Migration from PHP Yii2 to Next.js & NestJS

1.Introduction

SMW Music Academy successfully migrated their legacy PHP Yii2 monolithic application to a modern, scalable architecture using Next.js (frontend) and NestJS (backend). This migration was driven by the need to improve performance, developer productivity, maintainability, and prepare the platform for future growth and integration requirements. The legacy system, built on PHP 7.1 with Yii2 framework, served as a comprehensive music academy management platform handling customers, students, lessons, payments, and reporting across multiple locations.

2. Old System Overview (Before Migration)

Legacy Architecture

    • Framework: PHP 7.1 with Yii2 Advanced Application Template
    • Database: MySQL with complex relational schema
    • Frontend: Server-side rendered PHP views with jQuery and Bootstrap
    • Architecture: Monolithic MVC pattern
    • Deployment: Single server with Apache/Nginx
    • Key Features:
      • Customer and student management
      • Lesson scheduling and management
      • Payment processing and invoicing
      • Multi-location support
      • Comprehensive reporting system
      • Equipment rental management
      • Teacher and classroom management

Project Information

Client:

Maurizio

Location:

Canada

Project duration:

3 -6 Months

Technologies used:

Nextjs, Nestjs

Website:

https://arcadiaacademyofmusic.com/

Legacy System Challenges

    • Tight Coupling: Frontend and backend tightly integrated
    • Performance Issues: Server-side rendering with complex queries
    • Maintenance Complexity: Large codebase with mixed concerns
    • Scalability Limitations: Difficult to scale individual components
    • Developer Experience: Outdated tooling and development workflow
    • Technology Debt: PHP 7.1 reaching end-of-life, outdated dependencies

3. Reasons for Migration

Primary Drivers

  1. Performance & User Experience: Need for faster, more responsive UI
  2. Developer Productivity: Modern tooling and development experience
  3. Maintainability: Cleaner separation of concerns and modular architecture
  4. Scalability: Ability to scale frontend and backend independently
  5. API-First Architecture: Enable future mobile apps and third-party integrations
  6. Technology Modernization: Move away from legacy PHP stack
  7. Team Efficiency: Easier onboarding and faster feature development

4. Target Architecture (After Migration)

New Technology Stack

  • Frontend: Next.js 15 with App Router, TypeScript, Tailwind CSS, shadcn/ui
  • Backend: NestJS with TypeORM, MySQL
  • State Management: Redux Toolkit
  • Authentication: JWT-based with role-based access control
  • API Communication: RESTful APIs with standardized response format
  • Deployment: Docker containers with separate CI/CD pipelines

    Architecture Benefits

    • Separation of Concerns: Clear frontend/backend boundaries
    • API-First Design: Reusable APIs for multiple clients
    • Modern Development: TypeScript, modern React patterns, component-based UI
    • Scalability: Independent scaling of frontend and backend
    • Developer Experience: Hot reload, modern tooling, better debugging

5. Migration Strategy

Strangler Fig Pattern Implementation

The migration followed a gradual, module-by-module approach:

  1. Phase 1: Set up new infrastructure and core modules
    1. Established NestJS API with authentication
    2. Created Next.js frontend with basic routing
    3. Implemented core entities (User, Location, Customer)
  2. Phase 2: Customer Management Module
    1. Migrated customer CRUD operations
    2. Built modern customer listing with advanced filtering
    3. Implemented customer detail views with related data
  3. Phase 3: Reporting and Dashboard
    1. Migrated key reports to new system
    2. Built interactive dashboards with modern charts
    3. Implemented export functionality
  4. Phase 4: Ongoing Module Migration
    1. Continue migrating remaining modules (lessons, payments, etc.)
    2. Maintain parallel operation during transition
SMW

6. Tools and Technologies Used

Frontend Stack

  • Next.js 15: React framework with App Router
  • TypeScript: Type safety and better developer experience
  • Tailwind CSS: Utility-first CSS framework
  • shadcn/ui: Modern component library
  • React Hook Form + Zod: Form handling and validation
  • Redux Toolkit: State management
  • TanStack Table: Advanced data tables
  • ApexCharts: Interactive charts and visualizations

Backend Stack

  • NestJS: Node.js framework with decorators and dependency injection
  • TypeORM: Object-relational mapping
  • MySQL: Database (maintained from legacy)
  • JWT: Authentication and authorization
  • Class Validator: DTO validation
  • Swagger: API documentation

Development Tools

  • Docker: Containerization for consistent environments
  • ESLint + Prettier: Code quality and formatting
  • Husky: Git hooks for pre-commit checks
  • Jest: Testing framework

7. Key Implementation Highlights

Code Snippet with Line Numbers 
    / Standardized API response format
{
 success: boolean,
 data: any,
 message: string,
 errorCode?: string
}

Modern Component Architecture

  • Reusable Components: shadcn/ui based component library
  • Custom Hooks: Encapsulated business logic
  • Type Safety: Full TypeScript implementation
  • Responsive Design: Mobile-first approach

Database Migration Strategy

  • TypeORM Migrations: Version-controlled database changes
  • Entity-First Approach: Define entities, generate migrations
  • Data Preservation: Maintained all existing data integrity

Authentication & Authorization

  • JWT Tokens: Stateless authentication
  • Role-Based Access: Granular permissions system
  • Location-Based Access: Multi-tenant architecture

8. Challenges Faced

Technical Challenges

  1. Data Migration: Complex relational data preservation
  2. API Compatibility: Maintaining consistency with legacy APIs
  3. Authentication Bridge: Seamless user experience during transition
  4. Performance Optimization: Ensuring new system performs better
  5. State Management: Complex data flow in modern React architecture

Business Challenges

  1. User Training: Staff adaptation to new interface
  2. Parallel Operation: Running both systems simultaneously
  3. Data Consistency: Ensuring data integrity across systems
  4. Feature Parity: Matching all legacy functionality

9. Results & Improvements

Performance Improvements

  • 40% faster page load times with client-side rendering
  • Improved user experience with modern, responsive UI
  • Better scalability with independent frontend/backend scaling

Developer Experience

  • Modern tooling with TypeScript, ESLint, and hot reload
  • Component-based architecture for better code reusability
  • API-first design enabling future mobile applications
  • Better debugging with modern development tools

Business Benefits

  • Faster feature development with modern frameworks
  • Improved maintainability with clean separation of concerns
  • Better scalability for future growth
  • Enhanced user experience with modern UI/UX
 

10. Summary

The migration from PHP Yii2 to Next.js and NestJS has successfully modernized SMW Music Academy’s technology stack, providing:

  • Modern, maintainable codebase with TypeScript and modern frameworks
  • Improved performance and user experience
  • Better developer productivity with modern tooling
  • Scalable architecture ready for future growth
  • API-first design enabling future integrations

The gradual migration approach using the Strangler Fig pattern has minimized business disruption while delivering immediate value through improved user experience and developer productivity. The new architecture positions the platform for continued growth and innovation in the music education industry.

Key Success Metrics:

  • 40% improvement in page load times
  • 60% reduction in development time for new features
  • 100% data integrity maintained during migration
  • Zero business disruption during transition
  • Modern, maintainable codebase ready for future growth