Overview
Maintenance mode locks non-admin users out of the system during deployments, schema migrations, or critical updates. This ensures data consistency and prevents user actions from interfering with system changes.
Only users with the ADMIN role can access the system during maintenance mode.
How It Works
When maintenance mode is enabled:
- Admin users: Full system access continues
- All other users (Supervisors, Credit Officers): Receive a 503 error with message:
System is currently under maintenance. Please try again later.
The check occurs at the authentication middleware level (backend/src/middlewares/auth.middleware.ts:78-89).
API Endpoint
Get Maintenance Status
GET /api/settings/maintenance
{
"success": true,
"data": {
"maintenanceMode": false
}
}
Toggle Maintenance Mode
PUT /api/settings/maintenance
Content-Type: application/json
{
"enabled": true
}
{
"success": true,
"data": {
"maintenanceMode": true
},
"message": "Maintenance mode enabled successfully"
}
Only ADMIN users can enable/disable maintenance mode. This endpoint is protected by the requireRole(Role.ADMIN) middleware.
Database Schema
Maintenance mode state is stored in the CompanySetting model:
model CompanySetting {
id String @id
maintenanceMode Boolean @default(false)
// ... other fields
}
backend/prisma/schema.prisma:366
Use Cases
1. Safe Schema Migrations
# Step 1: Enable maintenance mode via API or UI
curl -X PUT https://your-api.com/api/settings/maintenance \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
# Step 2: Run database migration
npx prisma migrate deploy
# Step 3: Deploy new code
git push production main
# Step 4: Disable maintenance mode
curl -X PUT https://your-api.com/api/settings/maintenance \
-H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
2. Emergency System Lockdown
If critical issues are detected:
- Enable maintenance mode immediately
- Investigate and resolve the issue
- Verify system integrity
- Disable maintenance mode
3. Data Restoration
When restoring from backup:
- Enable maintenance mode
- Run restore operation (see Backups)
- Verify data integrity
- Disable maintenance mode
Implementation Details
Backend Check Flow
-
Authentication Middleware (
auth.middleware.ts:78):
// Check maintenance mode (allow admins only)
if (user.role !== "ADMIN") {
const isMaintenance = await SettingsService.isMaintenanceModeActive();
if (isMaintenance) {
return ApiResponseUtil.error(
res,
"System is currently under maintenance. Please try again later.",
503
);
}
}
-
Settings Service (
settings.service.ts:358):
static async isMaintenanceModeActive(): Promise<boolean> {
const settings = await prisma.companySetting.findFirst({
select: { maintenanceMode: true },
});
return settings?.maintenanceMode ?? false;
}
Audit Logging
Maintenance mode toggles are automatically logged via the auditLog middleware:
auditLog("MAINTENANCE_MODE_TOGGLED", "Settings")
GET /api/audit-logs?action=MAINTENANCE_MODE_TOGGLED
Best Practices
Communicate in advance
Notify users 24-48 hours before scheduled maintenance via email or system announcement.
Choose off-peak hours
Enable maintenance mode during periods of lowest user activity (typically late night/early morning).
Test in staging first
Always test deployment procedures in a staging environment before production.
Monitor actively
Keep the health check endpoint available during maintenance: GET /api/health
Document the change
Record the reason for maintenance in audit logs or deployment notes.
Frontend Integration
When the frontend receives a 503 response, display a user-friendly maintenance page:
if (error.response?.status === 503) {
// Show maintenance banner
return {
message: "System is under maintenance. We'll be back shortly!",
retryAfter: 300 // seconds
};
}
