# 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.

---