infoscreen/userrole-management.md

User Role Management Integration Guide

This document outlines a step-by-step workpath to introduce user management and role-based access control (RBAC) into the infoscreen_2025 project. It is designed to minimize friction and allow incremental rollout.

---

1. Define Roles and Permissions

• Roles:
  • superadmin: Developer, can edit all settings (including critical/system settings), manage all users.
  • admin: Organization employee, can edit all organization-relevant settings, manage users (except superadmin), manage groups/clients.
  • editor: Can create, read, update, delete (CRUD) events and media.
  • user: Can view events only.
• Permission Matrix:
  • See summary in the main design notes above for CRUD rights per area.

---

2. Extend Database Schema

• Add a role column to the users table (Enum: superadmin, admin, editor, user; default: user).
• Create an Alembic migration for this change.
• Update SQLAlchemy models accordingly.

---

3. Seed Initial Superadmin

• Update server/init_defaults.py to create a default superadmin user (with secure password, ideally from env or prompt).

---

4. Backend: Auth Context and Role Exposure

• Ensure current user is determined per request (session or token-based).
• Add /api/me endpoint to return current user's id, username, and role.

---

5. Backend: Permission Decorators

• Implement decorators (e.g., @require_role('admin'), @require_any_role(['editor','admin','superadmin'])).
• Apply to sensitive routes:
  • User management (admin+)
  • Program settings (admin/superadmin)
  • Event settings (admin+)
  • Event CRUD (editor+)

---

6. Frontend: Role Awareness and Gating

• Add a useCurrentUser() hook or similar to fetch /api/me and store role in context.
• Gate navigation and UI controls based on role:
  • Hide or disable settings/actions not permitted for current role.
  • Show/hide user management UI for admin+ only.

---

7. Frontend: User Management UI

• Add a Users page (admin+):
  • List users (GridComponent)
  • Create/invite user (Dialog)
  • Set/reset role (DropDownList, prevent superadmin assignment unless current is superadmin)
  • Reset password (Dialog)

---

8. Rollout Strategy

• Stage 1: Implement model, seed, and minimal enforcement (now)
• Stage 2: Expand backend enforcement and frontend gating (before wider testing)
• Stage 3: Polish UI, add audit logging if needed (before production)

---

9. Testing

• Test each role for correct access and UI visibility.
• Ensure superadmin cannot be demoted or deleted by non-superadmin.
• Validate that critical settings are only editable by superadmin.

---

10. Optional: Audit Logging

• For production, consider logging critical changes (role changes, user creation/deletion, settings changes) for traceability.

---

References

• See models/models.py, server/routes/, and dashboard/src/ for integration points.
• Syncfusion: Use GridComponent, Dialog, DropDownList for user management UI.

---

This guide is designed for incremental, low-friction integration. Adjust steps as needed for your workflow and deployment practices.

---

Stage 1: Concrete Step-by-Step Checklist

1. Extend the User Model

• Add a role column to the users table in your SQLAlchemy model (models/models.py).
• Use an Enum for roles: superadmin, admin, editor, user (default: user).
• Create an Alembic migration to add this column to the database.

2. Seed a Superadmin User ✅

• Update server/init_defaults.py to create a default superadmin user with a secure password (from environment variable).
• Ensure this user is only created if not already present.
• Status: Completed. See server/init_defaults.py - requires DEFAULT_SUPERADMIN_PASSWORD environment variable.

3. Expose Current User Role ✅

• Add a /api/me endpoint (e.g., in server/routes/auth.py) that returns the current user's id, username, and role.
• Ensure the frontend can fetch and store this information on login or page load.
  • Status: Completed. See:
    • Backend: server/routes/auth.py (login, logout, /me, /check endpoints)
    • Frontend: dashboard/src/apiAuth.ts and dashboard/src/useAuth.tsx
    • Permissions: server/permissions.py (decorators for route protection)

4. Implement Minimal Role Enforcement ✅

• Decorators added in server/permissions.py: require_auth, require_role, editor_or_higher, admin_or_higher, superadmin_only.
• Applied to sensitive endpoints:
  • Groups (admin+): create, update, delete, rename (server/routes/groups.py)
  • Clients (admin+): sync-all-groups, set description, bulk group update, patch, restart, delete (server/routes/clients.py)
  • Academic periods (admin+): set active (server/routes/academic_periods.py)
  • Events (editor+): create, update, delete, delete occurrence, detach occurrence (server/routes/events.py)
  • Event media (editor+): filemanager operations/upload, metadata update (server/routes/eventmedia.py)
  • Event exceptions (editor+): create, update, delete (server/routes/event_exceptions.py)
  • Conversions (editor+): ensure conversion (server/routes/conversions.py)
• Superadmin dev bypass: In development (ENV=development), superadmin bypasses checks for unblocking.

5. Test the Flow

• Confirm that the superadmin can access all protected endpoints.
• Confirm that users with other roles are denied access to protected endpoints.
• Ensure the frontend can correctly gate UI elements based on the current user's role.

---