tabungin/docs/guides/testing-guide.md

Maintenance Mode - Testing Guide

✅ Fixed Implementation

What Was Wrong:

The original implementation had a critical flaw - it checked request.user which doesn't exist until AFTER the JWT guard runs. This meant:

• Admins would also be blocked
• The guard couldn't distinguish between admin and regular users

What Was Fixed:

• MaintenanceGuard now manually verifies JWT tokens using JwtService
• Extracts user role from token payload
• Allows admins through, blocks everyone else
• Works independently of the JWT guard

---

🧪 How to Test Maintenance Mode

Prerequisites:

1. Have at least 2 user accounts:
   • One admin account (role: 'admin')
   • One regular user account (role: 'user')
2. Both API and Web servers running

---

Test Scenario 1: Enable Maintenance Mode

Step 1: Login as Admin

1. Go to http://localhost:5174/auth/login
2. Login with admin credentials
3. Navigate to http://localhost:5174/admin/settings

Step 2: Enable Maintenance

1. Find "Maintenance Mode" section
2. Toggle the switch to ON
3. Optionally change the message to: "We're upgrading! Back in 10 minutes."
4. Click "Save Settings"
5. You should see success toast

Step 3: Verify Admin Still Has Access

1. Stay logged in as admin
2. Navigate to different admin pages:
   - /admin (Dashboard)
   - /admin/users
   - /admin/plans
3. All should work normally ✅
4. Try accessing main app: http://localhost:5174/
5. Admin should see maintenance page ❌ (this is expected - only admin panel works)

---

Test Scenario 2: Regular User Experience

Step 1: Open Incognito/Private Window

1. Open new incognito window
2. Go to http://localhost:5174

Step 2: Try to Access Without Login

1. You'll be redirected to login page
2. Try to login with regular user credentials
3. After successful login, you should see MAINTENANCE PAGE ✅
4. The page should display your custom message

Step 3: Verify User is Blocked

1. Try to navigate to any route:
   - /
   - /wallets
   - /transactions
2. All should show maintenance page ✅
3. Click "Refresh Page" button
4. Should still show maintenance (because it's still ON)

---

Test Scenario 3: Disable Maintenance Mode

Step 1: As Admin, Disable Maintenance

1. Go back to admin window (still logged in)
2. Navigate to /admin/settings
3. Toggle "Maintenance Mode" to OFF
4. Click "Save Settings"

Step 2: Verify User Can Access Again

1. Go to incognito window (with regular user)
2. Click "Refresh Page" button
3. User should now see the normal app ✅
4. Try navigating to different pages - all should work

---

📊 Expected Behavior Matrix

User Type	Maintenance OFF	Maintenance ON
Not Logged In	Can login	Can login, then see maintenance page
Regular User	Full access	Maintenance page on all routes
Admin User	Full access	Admin panel works, main app shows maintenance

---

🔍 How to Verify It's Working

Check 1: API Returns 503

Open browser DevTools (F12) → Network tab:

1. With maintenance ON, as regular user
2. Try to access any protected route
3. Look for API calls
4. Should see 503 status code
5. Response body should have:
   {
     "statusCode": 503,
     "message": "Your custom message",
     "maintenanceMode": true
   }

Check 2: Admin Bypasses Maintenance

1. With maintenance ON, as admin
2. Open DevTools → Network tab
3. Navigate to /admin/users
4. API calls should return 200 OK (not 503)
5. Admin panel should work normally

Check 3: Database Config

Check the database directly:

SELECT * FROM "Config" WHERE key = 'maintenance_mode';
-- Should show: value = 'true' when ON, 'false' when OFF

SELECT * FROM "Config" WHERE key = 'maintenance_message';
-- Should show your custom message

---

🐛 Troubleshooting

Problem: Admin Also Sees Maintenance Page

Cause: JWT token might be invalid or expired Solution:

1. Logout and login again as admin
2. Check browser console for errors
3. Verify JWT_SECRET in .env matches between sessions

Problem: Regular User Can Still Access

Cause: Maintenance mode not actually enabled in DB Solution:

1. Check database: SELECT * FROM "Config" WHERE key = 'maintenance_mode'
2. If value is not 'true', manually update:

   UPDATE "Config" SET value = 'true' WHERE key = 'maintenance_mode';
   

3. Or toggle it again in Admin Settings

Problem: Maintenance Page Never Shows

Cause: Axios interceptor not set up properly Solution:

1. Check browser console for errors
2. Verify App.tsx has setupAxiosInterceptors call
3. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

Problem: Auth Routes Also Blocked

Cause: @SkipMaintenance decorator missing Solution:

1. Verify auth.controller.ts has @SkipMaintenance on login/register
2. Restart API server

---

🎯 Quick Test Checklist

• Admin can enable maintenance mode
• Admin can customize maintenance message
• Admin can still access admin panel when maintenance is ON
• Regular user sees maintenance page when maintenance is ON
• Maintenance page displays custom message
• Refresh button works on maintenance page
• Admin can disable maintenance mode
• Regular user can access app after maintenance is OFF
• Login/register still work during maintenance
• Health check endpoints still work during maintenance

---

📝 Notes

Routes That Always Work (Even During Maintenance):

• /health - Health check
• /health/db - Database check
• /auth/login - Login
• /auth/register - Register
• /auth/verify-otp - OTP verification
• /auth/google - Google OAuth
• /admin/* - All admin routes (for admins only)

Routes That Get Blocked:

• / - Main dashboard
• /wallets - Wallets page
• /transactions - Transactions page
• /api/users/me - User profile
• /api/wallets - Wallet API
• /api/transactions - Transaction API
• Any other non-admin, non-auth route

How Admins Are Identified:

1. MaintenanceGuard extracts JWT token from Authorization header
2. Verifies token using JwtService
3. Checks if payload.role === 'admin'
4. If true, allows access
5. If false or no token, blocks with 503

---

🚀 Production Deployment Notes

Before Enabling Maintenance:

1. Notify users via email/notification
2. Set a clear maintenance message with expected duration
3. Schedule during low-traffic hours
4. Have rollback plan ready

During Maintenance:

1. Monitor admin panel access
2. Check logs for any issues
3. Test critical features before re-enabling

After Maintenance:

1. Disable maintenance mode
2. Monitor for any issues
3. Verify all features work
4. Notify users that system is back online

---

✅ Summary

Maintenance mode is now fully functional with proper admin bypass. The system:

• ✅ Blocks regular users when enabled
• ✅ Allows admins to continue working
• ✅ Shows professional maintenance page
• ✅ Displays custom admin messages
• ✅ Can be toggled on/off from Admin Settings
• ✅ Preserves auth functionality
• ✅ Keeps health checks working

Ready for production use!