Feature Owner : Joylynne Esportuno
Module : User Management and Enrollment
Priority : P3
Sprint #5 : Fully Implemented
Date : July 2, 2026
EXECUTIVE SUMMARY
What is this feature ?
Suspend User allows platform admins to suspend or unsuspend users and block suspended users from protected pages/APIs.
Why does it matter ?
Admins need a fast safety control for abusive, inactive, or policy-violating accounts.
What's the MVP scope ?
Admin action updates user status and middleware blocks suspended access. Audit history and timed suspension are out of scope.
1. USER PAIN POINT & SOLUTION
Without Suspend User
Admins may lack a reliable way to revoke access without deleting a user.
Pain Point
Emotional : Safety incidents feel urgent.
Functional : Manual access removal is risky.
Business Impact : Compliance and trust risk.
Current State (Already Implemented)
Admins suspend users and access is revoked consistently.
Marketing Hook
"Protect the platform without deleting user records."
2. 4D FRAMEWORK MAPPING
Diagnose
Identifies risky users in admin user management.
Design
Provides explicit status state.
Develop
Updates Supabase status and auth enforcement.
Deliver
Blocks suspended user access immediately on protected routes.
3. USER FLOWS
Entry Point
app/admin/manage-users/page.tsx.
Success Criteria
Suspended user cannot access protected pages/APIs; unsuspended user regains access.
Main Flow
Admin opens user management.
Admin selects Suspend.
API verifies admin role.
User status becomes Suspended.
Middleware redirects/blocks user.
Edge Cases
No user : Show not found.
API error : Keep previous status.
Permission denied : Non-admin cannot suspend.
Decision Points
IF status is Suspended, route to access revoked / 403.
ELSE allow protected access.
4. INFORMATION ARCHITECTURE
Primary Information
User name/email
Role
Status
Secondary Information
Clerk ID
Last updated
Actions
Primary CTA : Suspend / Unsuspend
Secondary Actions : View user, close dialog
5. WIREFRAMES
Excluded — Fully implemented.
6. WIREFLOWS
Excluded — Fully implemented.
7. PROTOTYPE
Excluded — Fully implemented.
8. BACKEND SCHEMA
Database Tables
app_users.statusapp_users.clerk_id
Constraints
Only admin users can suspend or unsuspend
Suspended users must be blocked from protected pages/APIs
Unsuspend should restore active access without changing role or ownership data
9. API ENDPOINTS
Endpoint 1: GET /api/admin/list-users
Purpose: Loads the user table used by platform admins.
Auth: Admin role required.
Response Data: User ID, Clerk ID, role, status, and profile fields.
Endpoint 2: POST /api/admin/suspend-user
Purpose: Marks a user as suspended and/or mirrors suspension to the auth provider where implemented.
Auth: Admin role required.
Request Body: Target user identifier, currently using Clerk ID in the admin UI flow.
Endpoint 3: POST /api/admin/unsuspend-user
Purpose: Restores suspended user to active access.
Auth: Admin role required.
Request Body: Target user identifier.
10. DATA REQUIREMENTS
Frontend Needs
User display name, email, role, status, and Clerk ID
Selected user state for suspend/unsuspend dialogs
Loading/error state for admin action
Updated status after action succeeds
Backend Needs
Authenticated admin identity and role
Target user's
app_usersrowTarget user's
clerk_idCurrent and next status values
API Calls Frontend Will Make
Load users for the admin table
Suspend selected user
Unsuspend selected user
Refetch or locally update table after action
Caching Strategy
User status should be refreshed after mutations. Avoid long-lived cache for admin user lists because access state is sensitive.
11. PERFORMANCE CONSIDERATIONS
Database Optimization
Middleware status lookup should query by indexed
clerk_idor equivalent stable auth identifier. Admin list queries should paginate/search if user count grows.
Client Optimization
Use optimistic UI carefully. Because this is access control, prefer refetching the affected user row/list after mutation.
Caching Strategy
Do not cache suspended status in a way that delays enforcement. Middleware should use fresh-enough data for protected requests.
API Response Time
Suspend/unsuspend should complete quickly, but correctness is more important than purely optimistic feedback.
12. SECURITY & AUTHORIZATION
Who Can Access This Feature?
Platform Admin: Can suspend/unsuspend users.
Non-Admin Users: No access to admin action routes.
Suspended User: Cannot access protected routes/APIs.
Authorization Logic
Admin routes must require admin role before listing users or changing status. Middleware must check authenticated user's status on protected requests.
13. ERROR HANDLING
401 Unauthorized: Prompt admin to sign in again. Do not expose user management data.
404 User Not Found: Show a user-not-found message and refresh the user list, since the row may have been removed or is outside admin scope.
500 Update Failure: Do not update the UI status permanently. Show failure toast and refetch the user row/list.
14. TESTING CHECKLIST
Happy Path
Admin can suspend
Admin can unsuspend
User row status updates after action
Edge Cases
Non-admin blocked
Suspended page request redirects
Suspended API request returns 403
Missing user ID returns not found/validation error
15. OPEN QUESTIONS
For Frontend:
Should suspension include a required reason field in the dialog?
Should suspended users see appeal/support instructions?
For Backend:
Should suspension include an audit trail?
16. OUT OF SCOPE
Timed suspension
Appeal workflow
Full audit log
17. SUCCESS METRICS
Suspension action success rate
Bocked suspended access attempts
Admin support resolution time
18. DEPENDENCIES
This feature depends on:
Admin manage-users page
app_users.statusAuth middleware
Admin role checks
These features depend on this:
Platform access control
Protected API/page security
Admin user operations
19. TIMELINE & OWNERSHIP
Backend: Joylynne Esportuno & Sean Caintic
Frontend: Joylynne Esportuno & Sean Caintic
QA: Clyde Ador
Estimated Completion: Fully implemented
