feat: reorganize admin settings with tabbed interface and documentation
- Reorganized admin settings into tabbed interface (General, Security, Payment Methods) - Vertical tabs on desktop, horizontal scrollable on mobile - Moved Payment Methods from separate menu to Settings tab - Fixed admin profile reuse and dashboard blocking - Fixed maintenance mode guard to use AppConfig model - Added admin auto-redirect after login (admins → /admin, users → /) - Reorganized documentation into docs/ folder structure - Created comprehensive README and documentation index - Added PWA and Web Push notifications to to-do list
This commit is contained in:
dwindown
294
MAINTENANCE_MODE_IMPLEMENTATION.md
Normal file
294
MAINTENANCE_MODE_IMPLEMENTATION.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user