mivita/dev/subdomain-optimization/implementation-guide.md

Implementation Guide - Mivita Subdomain Optimization

Overview

This guide provides step-by-step instructions for implementing the optimized multi-domain and subdomain architecture for the Mivita application.

Prerequisites

• Backup of current system
• Test environment available
• Access to web server configuration
• Understanding of Laravel routing and middleware

Phase 1: Foundation Setup

Step 1: Create New Service Classes

1. Create DomainService

   # Copy from dev/subdomain-optimization/DomainService.php
   cp dev/subdomain-optimization/DomainService.php app/Services/DomainService.php
   

2. Create DomainContext

   # Create Domain directory and copy context
   mkdir -p app/Domain
   cp dev/subdomain-optimization/DomainContext.php app/Domain/DomainContext.php
   

3. Create New Middleware

   # Copy enhanced middleware
   cp dev/subdomain-optimization/DomainResolver.php app/Http/Middleware/DomainResolver.php
   

Step 2: Register New Services

Add to config/app.php:

'providers' => [
    // ... existing providers
    App\Providers\DomainServiceProvider::class,
],

Create app/Providers/DomainServiceProvider.php:

<?php

namespace App\Providers;

use App\Services\DomainService;
use Illuminate\Support\ServiceProvider;

class DomainServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(DomainService::class);
    }

    public function boot()
    {
        //
    }
}

Step 3: Update Kernel Configuration

Add new middleware to app/Http/Kernel.php:

protected $middleware = [
    // ... existing middleware
    \App\Http\Middleware\DomainResolver::class,
];

protected $middlewareGroups = [
    'web' => [
        // Remove old Subdomain middleware
        // \App\Http\Middleware\Subdomain::class,
        // ... other middleware
    ],
];

Phase 2: Route Structure Migration

Step 1: Create New Route Structure

# Create new directory structure
mkdir -p routes/domains/subdomains
mkdir -p routes/shared/crm
mkdir -p routes/shared/api

# Create placeholder files
touch routes/domains/main.php
touch routes/domains/shop.php
touch routes/domains/subdomains/crm.php
touch routes/domains/subdomains/portal.php
touch routes/domains/subdomains/checkout.php
touch routes/domains/subdomains/user-shops.php
touch routes/shared/legal.php
touch routes/shared/common.php

Step 2: Migrate Existing Routes

1. Legal Routes (move to routes/shared/legal.php)

   • Extract legal routes from all current route files
   • Remove duplicates
   • Standardize naming

2. Main Domain Routes (move to routes/domains/main.php)

   • Extract routes from routes/main.php
   • Clean up and organize

3. CRM Routes (move to routes/domains/subdomains/crm.php)

   • Extract routes from routes/crm.php
   • Split into sub-files for organization

4. User Shop Routes (move to routes/domains/subdomains/user-shops.php)

   • Extract routes from routes/subdomain.php
   • Remove domain-specific logic (handled by middleware)

Step 3: Update Route Service Provider

Replace app/Providers/RouteServiceProvider.php with the optimized version:

cp dev/subdomain-optimization/RouteServiceProvider.php app/Providers/RouteServiceProvider.php

Phase 3: Testing and Validation

Step 1: Unit Tests

Create tests for new components:

php artisan make:test DomainServiceTest --unit
php artisan make:test DomainContextTest --unit
php artisan make:test DomainResolverTest

Step 2: Feature Tests

Test each domain type:

php artisan make:test MainDomainTest
php artisan make:test CrmDomainTest
php artisan make:test UserShopDomainTest
php artisan make:test CheckoutDomainTest
php artisan make:test PortalDomainTest

Step 3: Manual Testing

Test each domain type manually:

1. Main Domain (mivita.care)

   • Homepage loads correctly
   • Registration works
   • Contact forms work
   • Legal pages accessible

2. CRM Domain (my.mivita.care)

   • Login system works
   • User dashboard accessible
   • Admin functions work
   • Session management correct

3. User Shops ({slug}.mivita.care)

   • Valid shops load correctly
   • Invalid shops redirect properly
   • Shopping cart functionality works
   • Session isolation working

4. Checkout Domain (checkout.mivita.care)

   • Payment processing works
   • Transaction handling correct
   • Security measures in place

5. Portal Domain (in.mivita.care)

   • Customer login works
   • Portal functionality accessible
   • Data isolation correct

Phase 4: Performance Optimization

Step 1: Enable Caching

1. Route Caching

   php artisan route:cache
   

2. User Shop Caching

   • Configure Redis/Memcached
   • Test cache invalidation
   • Monitor cache hit rates

Step 2: Database Optimization

1. Add Indexes

   CREATE INDEX idx_user_shops_slug_active ON user_shops (slug, active);
   CREATE INDEX idx_users_shop_active ON users (id) WHERE shop_active = 1;
   

2. Query Optimization

   • Review N+1 queries
   • Optimize user shop lookups
   • Add eager loading where needed

Step 3: Monitoring Setup

1. Application Monitoring

   • Add performance metrics
   • Monitor response times per domain
   • Track error rates by domain type

2. Cache Monitoring

   • Monitor cache hit/miss rates
   • Track cache memory usage
   • Set up cache warming

Phase 5: Deployment Strategy

Step 1: Feature Flags

Implement feature flags for gradual rollout:

// In DomainResolver middleware
if (config('features.new_domain_resolver', false)) {
    // Use new logic
} else {
    // Fall back to old middleware
}

Step 2: Blue-Green Deployment

1. Prepare Blue Environment

   • Deploy new code to blue environment
   • Test all functionality
   • Verify performance metrics

2. Switch Traffic

   • Gradually route traffic to blue
   • Monitor for issues
   • Ready to rollback if needed

Step 3: Monitoring During Deployment

1. Real-time Monitoring

   • Response times
   • Error rates
   • User shop accessibility
   • Payment processing success

2. Rollback Triggers

   • Error rate > 1%
   • Response time > 2x baseline
   • Payment failures > 0.1%
   • User complaints

Rollback Plan

Immediate Rollback (< 5 minutes)

1. Revert Middleware

   // In Kernel.php, re-enable old middleware
   \App\Http\Middleware\Subdomain::class,
   

2. Revert Route Service Provider

   git checkout HEAD~1 app/Providers/RouteServiceProvider.php
   

3. Clear Caches

   php artisan route:clear
   php artisan config:clear
   php artisan cache:clear
   

Full Rollback (< 30 minutes)

1. Revert All Changes

   git revert <commit-hash>
   

2. Redeploy Previous Version

   # Deploy previous known-good version
   

3. Verify Functionality

   • Test all domain types
   • Verify user shop access
   • Check payment processing

Configuration Management

Environment Variables

Add to .env:

# Domain optimization feature flags
DOMAIN_RESOLVER_ENABLED=true
DOMAIN_CACHE_ENABLED=true
DOMAIN_CACHE_TTL=3600

# Monitoring
DOMAIN_MONITORING_ENABLED=true
DOMAIN_PERFORMANCE_TRACKING=true

Configuration Files

Update config/domains.php:

<?php

return [
    'cache_ttl' => env('DOMAIN_CACHE_TTL', 3600),
    'monitoring_enabled' => env('DOMAIN_MONITORING_ENABLED', false),
    'performance_tracking' => env('DOMAIN_PERFORMANCE_TRACKING', false),

    'fixed_subdomains' => ['my', 'in', 'checkout'],

    'middleware_stacks' => [
        'main' => ['web'],
        'crm' => ['web', 'auth'],
        'portal' => ['web', 'auth:customers'],
        'checkout' => ['web', 'checkout'],
        'user-shop' => ['web', 'subdomain'],
    ],
];

Maintenance Procedures

Regular Maintenance

1. Weekly Cache Clearing

   # Clear expired user shop cache entries
   php artisan domain:cache:clean
   

2. Monthly Performance Review

   • Review response time metrics
   • Check cache hit rates
   • Analyze error patterns

3. Quarterly Domain Audit

   • Review user shop validity
   • Clean up inactive shops
   • Update domain configurations

Emergency Procedures

1. User Shop Outage

   • Identify affected shops
   • Clear specific cache entries
   • Notify affected users

2. Domain Resolution Issues

   • Check DNS configuration
   • Verify middleware configuration
   • Test domain parsing logic

3. Performance Degradation

   • Check cache status
   • Review database performance
   • Scale resources if needed

Success Metrics

Performance Metrics

• Response Time: < 200ms for cached requests
• Cache Hit Rate: > 95% for user shop lookups
• Error Rate: < 0.1% across all domains
• Uptime: > 99.9% per domain type

Business Metrics

• User Shop Accessibility: 100% for active shops
• Payment Success Rate: > 99.5%
• Customer Satisfaction: No complaints about domain issues
• Development Velocity: Faster feature development per domain

Technical Metrics

• Code Maintainability: Reduced cyclomatic complexity
• Test Coverage: > 90% for domain-related code
• Documentation: All new components documented
• Security: No domain-based security vulnerabilities