# 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:
  ```json
  {
    "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**

- [x] Backend maintenance guard implemented
- [x] Skip maintenance decorator created
- [x] Global guard registered
- [x] Auth routes exempted
- [x] Admin routes exempted
- [x] Health check routes exempted
- [x] Frontend maintenance page created
- [x] Axios interceptor implemented
- [x] App-level integration completed
- [x] Admin settings toggle working
- [x] Custom message support added
- [x] All Indonesian text translated
- [x] 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!