tabungin/MAINTENANCE_MODE_IMPLEMENTATION.md

Maintenance Mode Implementation

✅ COMPLETE: Maintenance Mode Feature Fully Implemented

Overview

Implemented a complete maintenance mode system that allows admins to temporarily disable user access to the application while keeping admin access available. The system is controlled via a toggle in the Admin Settings page.

---

🎯 Features Implemented

1. Backend (API)

MaintenanceGuard (/apps/api/src/common/guards/maintenance.guard.ts)

• Global guard that checks maintenance mode status from database
• Automatically blocks all requests when maintenance mode is active
• Exceptions:
  • Admin users can still access the system
  • Routes decorated with @SkipMaintenance() are exempt
• Returns 503 Service Unavailable with custom maintenance message

SkipMaintenance Decorator (/apps/api/src/common/decorators/skip-maintenance.decorator.ts)

• Decorator to mark routes that should bypass maintenance mode
• Applied to:
  • Health check endpoints
  • Auth endpoints (login, register, OTP, Google OAuth)
  • All admin endpoints

Global Guard Registration (/apps/api/src/app.module.ts)

• MaintenanceGuard registered as APP_GUARD
• Runs on every request automatically

Protected Routes

Routes that bypass maintenance mode:

• /health - Health check
• /health/db - Database health check
• /auth/login - User login
• /auth/register - User registration
• /auth/verify-otp - OTP verification
• /auth/google - Google OAuth
• /auth/google/callback - Google OAuth callback
• /admin/* - All admin routes (for admin users only)

---

2. Frontend (Web)

MaintenancePage Component (/apps/web/src/components/pages/MaintenancePage.tsx)

• Beautiful, user-friendly maintenance page
• Displays custom maintenance message from admin
• Includes refresh button to check if maintenance is over
• Responsive design with proper styling

Axios Interceptor (/apps/web/src/utils/axiosSetup.ts)

• Intercepts all API responses
• Detects 503 status with maintenanceMode: true
• Triggers maintenance page display
• Extracts custom message from response

App-Level Integration (/apps/web/src/App.tsx)

• Maintenance mode state management
• Axios interceptor setup on app initialization
• Conditional rendering of maintenance page
• Preserves theme settings during maintenance

---

📝 How It Works

Activation Flow:

1. Admin navigates to Admin Settings page
2. Admin toggles "Maintenance Mode" switch to ON
3. Admin can customize the maintenance message
4. Admin clicks "Save Settings"
5. System updates maintenance_mode config in database to true

User Experience:

1. User makes any API request (e.g., loading dashboard, creating transaction)
2. MaintenanceGuard intercepts the request
3. Guard checks if user is admin:
   • If admin: Request proceeds normally
   • If regular user: Returns 503 error with maintenance message
4. Frontend axios interceptor catches 503 error
5. MaintenancePage is displayed to user
6. User can click "Refresh" to check if maintenance is over

Deactivation Flow:

1. Admin (still has access) navigates to Admin Settings
2. Admin toggles "Maintenance Mode" switch to OFF
3. Admin clicks "Save Settings"
4. System updates maintenance_mode config to false
5. Regular users can now access the application again

---

🔧 Configuration

Database Config Keys:

• maintenance_mode (system category)

  • Type: boolean (stored as string "true"/"false")
  • Default: false
  • Controls whether maintenance mode is active

• maintenance_message (system category)

  • Type: text
  • Default: "System is under maintenance. Please try again later."
  • Custom message displayed to users

Admin Settings UI:

Located in: /admin/settings

Maintenance Mode Section:

• Toggle switch to enable/disable
• Text area to customize message
• Visual warning (red border) when enabled
• Save button to apply changes

---

📁 Files Created/Modified

Created Files:

1. /apps/api/src/common/guards/maintenance.guard.ts - Maintenance guard
2. /apps/api/src/common/decorators/skip-maintenance.decorator.ts - Skip decorator
3. /apps/web/src/components/pages/MaintenancePage.tsx - Maintenance UI
4. /apps/web/src/utils/axiosSetup.ts - Axios interceptor

Modified Files:

1. /apps/api/src/app.module.ts - Registered global guard
2. /apps/api/src/health/health.controller.ts - Added @SkipMaintenance
3. /apps/api/src/auth/auth.controller.ts - Added @SkipMaintenance to auth routes
4. /apps/api/src/admin/admin-config.controller.ts - Added @SkipMaintenance
5. /apps/api/src/admin/admin-users.controller.ts - Added @SkipMaintenance
6. /apps/api/src/admin/admin-plans.controller.ts - Added @SkipMaintenance
7. /apps/api/src/admin/admin-payments.controller.ts - Added @SkipMaintenance
8. /apps/api/src/admin/admin-payment-methods.controller.ts - Added @SkipMaintenance
9. /apps/web/src/App.tsx - Added maintenance mode handling
10. /apps/web/src/components/admin/pages/AdminSettings.tsx - Already has toggle UI
11. /apps/web/src/components/admin/pages/AdminPaymentMethods.tsx - Fixed Indonesian text
12. /apps/web/src/components/admin/pages/AdminSettings.tsx - Fixed Indonesian text

---

🧪 Testing Instructions

Test Maintenance Mode Activation:

1. Login as admin
2. Navigate to /admin/settings
3. Enable "Maintenance Mode" toggle
4. Optionally change the message
5. Click "Save Settings"
6. Open a new incognito window
7. Try to login as regular user
8. After login, you should see the maintenance page
9. Try to access any route - should show maintenance page

Test Admin Access During Maintenance:

1. With maintenance mode ON
2. Login as admin in a new window
3. Verify admin can access all admin routes
4. Verify admin dashboard works normally

Test Maintenance Mode Deactivation:

1. As admin, go to /admin/settings
2. Disable "Maintenance Mode" toggle
3. Click "Save Settings"
4. In the user's incognito window, click "Refresh"
5. User should now be able to access the application

Test Custom Message:

1. Enable maintenance mode
2. Set custom message: "We're upgrading our servers. Back in 30 minutes!"
3. Save settings
4. Verify users see the custom message on maintenance page

---

🎨 UI/UX Features

Maintenance Page Design:

• ⚠️ Yellow warning icon
• Clear "Under Maintenance" heading
• Custom message display
• Additional context text
• Refresh button with icon
• Responsive layout
• Dark mode support
• Professional appearance

Admin Settings UI:

• Clear toggle switch
• Descriptive labels
• Red warning styling when enabled
• Text area for custom message
• Save button with loading state
• Success/error toast notifications

---

🔒 Security Considerations

✅ Admin-only access during maintenance

• Only users with role: 'admin' can bypass maintenance mode
• Regular users are completely blocked

✅ Auth routes remain accessible

• Users can still login (but will see maintenance page after)
• Prevents lockout scenarios

✅ Health checks remain accessible

• Monitoring systems can still check app health
• Database connectivity can be verified

✅ No data loss

• Maintenance mode is non-destructive
• All user data remains intact
• Simply blocks access temporarily

---

📊 Status Codes

• 503 Service Unavailable - Returned when maintenance mode is active
• Response includes:

  {
    "statusCode": 503,
    "message": "System is under maintenance. Please try again later.",
    "maintenanceMode": true
  }
  

---

🚀 Future Enhancements

Potential improvements:

1. Scheduled Maintenance

   • Set start/end times for automatic activation/deactivation
   • Countdown timer on maintenance page

2. Partial Maintenance

   • Block specific features instead of entire app
   • Granular control per module

3. Notification System

   • Email users before maintenance
   • In-app notifications about upcoming maintenance

4. Maintenance History

   • Log all maintenance periods
   • Track admin who activated/deactivated

5. Status Page

   • Public status page showing system health
   • Historical uptime data

---

✅ Completion Checklist

• Backend maintenance guard implemented
• Skip maintenance decorator created
• Global guard registered
• Auth routes exempted
• Admin routes exempted
• Health check routes exempted
• Frontend maintenance page created
• Axios interceptor implemented
• App-level integration completed
• Admin settings toggle working
• Custom message support added
• All Indonesian text translated
• Documentation created

---

🎉 Summary

Maintenance mode is now fully functional!

Admins can:

• ✅ Toggle maintenance mode ON/OFF from Admin Settings
• ✅ Customize the maintenance message
• ✅ Continue using the admin panel during maintenance
• ✅ Monitor and manage the system

Users will:

• ✅ See a professional maintenance page when mode is active
• ✅ Receive custom messages from admins
• ✅ Be able to refresh to check if maintenance is over
• ✅ Have a smooth experience when maintenance ends

The system is production-ready and can be used for scheduled maintenance, emergency fixes, or system upgrades!