feat: config admin email, enhance RBAC

.env.example

@@ -7,6 +7,9 @@ ENVIRONMENT=production
 DEBUG=False
 SECRET_KEY=your-secret-key-here-generate-a-strong-random-key
 
+# Security & Access Control
+PLATFORM_ADMIN_EMAIL=your-new-email@company.com  # Email for platform admin OTP verification
+
 # Database - Supabase PostgreSQL (REQUIRED)
 # Get these from your Supabase project settings
 DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres

docs/agent/research.md

@@ -1,292 +1,315 @@
-I’ll review how user management works in this codebase (signup, auth, profile, roles, etc.), then give you a structured “grade” with what’s good, what’s weak, and concrete priority fixes.
-
-First I need to scan the project (code + docs) for user/account/profile flows. I’ll set up a small todo list for this review, then search through `src` and relevant docs, and come back with findings and recommendations.
-
-I’ll scan the code and docs for anything related to users, auth, accounts, and profiles, then summarize the end‑to‑end flow and grade it with concrete fixes you should do immediately. Let me search the repo first.
-
-
-# High‑Level Summary: User Management Flow
-
-From the code you’ve got a **pretty complete user lifecycle**:
-
-- **Identity & Auth**
-  - Supabase Auth is the **source of truth** for authentication (email/password, tokens).
-  - Backend uses Supabase JWT (Bearer token) in `Authorization` header.
-  - `get_current_user` (in `api/deps.py`) validates token via `supabase_auth.get_user`, then loads the local `User` row.
-  - `get_current_active_user` additionally requires `user.is_active == True`.
-
-- **Account Creation**
-
-  There are **two main creation paths**:
-
-  1. **Self‑Registration** (`POST /auth/register`)
-     - Calls `supabase_auth.sign_up` with `email`, `password`, and metadata (`first_name`, `last_name`, `phone`, `full_name`).
-     - Creates a local `User` mapped to `auth_user.id` with:
-       - `role = "platform_admin"` (**self‑registered users become platform admins**).
-       - `status = "invited"` (default from schema).
-       - `is_active = True`.
-     - Logs an audit event `register` and returns a token + basic user info.
-
-  2. **Invitation Flow** (`InvitationService.accept_invitation`)
-     - Admin (client/contractor/platform) invites users (not fully shown, but `accept_invitation` is).
-     - `accept_invitation`:
-       - Validates the invitation token.
-       - Ensures no existing user with the same email.
-       - Calls `supabase_auth.sign_up` and creates Supabase auth user.
-       - Creates local `User` with:
-         - `id = auth_user.id`.
-         - `email` from invitation.
-         - `name = first + last`.
-         - `phone` from acceptance or invitation.
-         - `role = invitation.invited_role`.
-         - `client_id` / `contractor_id` from invitation.
-         - `status = 'active'`, `is_active = True`.
-       - Marks invitation as accepted, commits, returns `access_token` + user details.
-
-- **Login** (`POST /auth/login`)
-  - Calls `supabase_auth.sign_in` to validate credentials and get `access_token`.
-  - Loads local `User` by `auth_user.id`.
-  - If no local user → `404 "User profile not found"`.
-  - If `is_active == False` → audit failed login + `403 "Account is inactive"`.
-  - Otherwise, audit success + returns token + basic user info.
-
-- **Profile Model & Building**
-
-  - `User` model (business profile) holds:
-    - Identity & contact: `name`, `email`, `phone`, `phone_alternate`, `display_name`, `id_number`.
-    - Org links: `client_id` or `contractor_id`.
-    - Role & status: `role`, `status`, `is_active`.
-    - Health & safety JSONB fields: `health_info`, `ppe_sizes`, plus emergency contacts.
-    - Location & geo: `current_location_*`, lat/long, updated timestamp.
-    - `additional_metadata` JSONB.
-  - Self‑service profile API (`api/v1/profile.py`):
-    - `GET /profile/me` returns:
-      - `basic_info` (from `BasicProfileResponse.from_orm(current_user)`).
-      - `health_info` (parsed from JSONB, with sensible defaults for missing fields).
-      - `ppe_sizes`.
-      - `location` details.
-      - Completion status: `ProfileService.calculate_profile_completion`.
-      - Counts: financial accounts, documents, asset assignments.
-
-- **Profile Permissions & Editing**
-
-  - `ProfileService.check_edit_permission` encodes **hierarchical access**:
-    - Self can edit own profile (subject to field‑level checks elsewhere).
-    - `platform_admin` can edit anyone.
-    - `client_admin`/`contractor_admin` can edit users in their org.
-    - `project_manager` / `dispatcher` can edit `field_agent`s in shared projects.
-  - `ProfileService.get_profile_permissions` turns this into fine‑grained booleans:
-    - `can_edit_basic_info`, `can_edit_health_info`, `can_edit_ppe_sizes`,
-      `can_edit_location`, `can_edit_financial_accounts`, `can_upload_documents`,
-      `can_edit_role`, `can_edit_status`, `can_assign_assets`, and corresponding view permissions.
-
-- **Roles & Authorization**
-
-  - `core/permissions.py` defines an `AppRole` enum and `ROLE_PERMISSIONS` map:
-    - Roles: `PLATFORM_ADMIN`, `CLIENT_ADMIN`, `CONTRACTOR_ADMIN`, `PROJECT_MANAGER`, `DISPATCHER`, `FIELD_AGENT`, `SALES_AGENT`, `SALES_MANAGER`.
-    - Each has a list of permission strings (e.g. `manage_projects`, `invite_users`, `view_team_performance`).
-    - `has_permission(role, permission)` supports generic checks.
-  - User update & admin actions (`UserService`):
-    - `check_update_permission`:
-      - `platform_admin` can change anyone.
-      - Org admins can update users in their org but cannot change org or promote to `platform_admin`.
-      - Self cannot use admin endpoints to change own role/status/org; must use profile APIs.
-    - `update_user`: handles basic fields, role, status, org changes, with audit‑style `changes` tracking.
-    - `change_user_status`: updates status + syncs `is_active` for `suspended`/`active`.
-    - `change_user_role`: validates and applies role changes.
-  - User admin endpoints (`api/v1/users.py` excerpts):
-    - `POST /users/{user_id}/status` → uses `UserService.change_user_status`, logs `status_change`.
-    - `POST /users/{user_id}/role` → uses `UserService.change_user_role`, logs `role_change`.
-
-- **Statuses**
-  - Documented statuses: `invited`, `pending_setup`, `active`, `suspended`.
-  - `change_user_status` uses `status` string + maps `suspended` and `active` to `is_active False/True`.
+I’ll re-grade the user management end‑to‑end with harsher standards, focusing on real risks and production readiness. I’ll structure it by lifecycle stages and call out concrete red flags, not just soft suggestions.
+I’ll focus on brutal, production-grade criteria across the full lifecycle: **account creation → auth → profile → admin/RBAC → security & DX**. I’ll be nitpicky on purpose.
 
 ---
 
-# What You Did Well
+## 1. Account Creation & Onboarding
 
-- **Clear separation of auth vs business profile**
-  - Supabase handles auth (passwords, tokens).
-  - Local `User` table holds business & authorization data.
-  - `get_current_user` cleanly bridges the two.
+### 1.1 Platform Admin Creation (OTP-based)
 
-- **Invitation‑based onboarding is solid**
-  - Token‑based invitations handled by `InvitationService`.
-  - Proper token validation, duplicate user check, and creation of both auth user + local profile.
-  - Good error handling and rollback on failure.
+From `auth.register`:
 
-- **Strong admin & profile permission model**
-  - `UserService.check_update_permission` and `ProfileService.check_edit_permission` encode a realistic hierarchy:
-    - Platform admin → org admin → manager/dispatcher → self.
-  - Separation between **self profile editing** and **admin updates** is good design.
-  - Field‑level permission booleans in `ProfilePermissions` are explicit and easily testable.
+- Self-registration is **explicitly disabled for normal users**.
+- `/auth/register` is a **platform-admin-only bootstrap**:
+  - It enforces an OTP flow via `OTPService`.
+  - OTP is sent to a **single hardcoded email** `lewiskimaru01@gmail.com`.
+  - Registration data is stored and only completed on OTP verification.
 
-- **Audit logging & rate limiting**
-  - Auth endpoints log audit events for `register` and `login` (both success and failure).
-  - Status/role changes log with old/new values and reason.
-  - Rate limits on `/auth/register` and `/auth/login` reduce brute force abuse.
+**What’s good**
 
-- **Role definitions & permissions table**
-  - `AppRole` enum and `ROLE_PERMISSIONS` map give a centralized RBAC definition.
-  - `has_permission` helper is generic and allows future route‑level enforceable checks.
+- **Separation of concerns**: Normal users don’t self-register; admins invite them.
+- **OTP requirement** for platform admin creation is a good hardening move.
+- **Audit logging** of registration attempts.
 
-- **Good data modeling for field agents**
-  - Health info and PPE sizes as JSONB with nice mapping to Pydantic response models.
-  - Location fields + `current_location_updated_at` support live ops / dispatch use cases.
-  - `additional_metadata` JSONB gives you flexibility without schema churn.
+**What’s bad**
+
+- **Hardcoded email** in production auth code is a red flag.
+  - Not configurable via env.
+  - Ties platform bootstrap to your personal email. That’s fine for a solo dev, bad for a team/product.
+- Single-path platform admin creation with **no rotation / delegation model**:
+  - What if that mailbox is compromised or lost?
+  - What if you need multiple platform admins in a controlled way?
+- The flow is **underspecified**:
+  - The actual `/otp/verify-public` completion code path isn’t visible here, so it’s hard to reason about:
+    - How roles are finally set.
+    - How many platform admins can be created.
+    - What happens after first bootstrap.
+
+**Grade: B-**
+
+Great *intent* and better than most hobby projects, but the hardcoding and opacity around the verification/completion path make it non-professional for a team environment.
+
+---
+
+### 1.2 Invitation-Based User Creation
+
+From `InvitationService.accept_invitation` + `User` model:
+
+- You validate token, check for existing users, then:
+  - Call Supabase `sign_up` with metadata.
+  - Create local `User` linked to `auth_user.id`.
+  - Set `role = invitation.invited_role`, `status = 'active'`, `is_active=True`, and org IDs.
+- Invitation status is updated and committed with rollback on error.
+
+**What’s good**
+
+- The **invitation flow is robust**:
+  - Token validation.
+  - Duplicate user check.
+  - Creates both auth user + local profile in a single transaction.
+- Correct linking between Supabase user ID and local `User.id`.
+- **Logging and rollback** are correct.
+
+**What’s bad**
+
+- **Status is immediately `active`** on first login. You have a `pending_setup` concept, but you’re not using it here.
+- No explicit **profile completeness step** gated before considering the account fully “usable”.
+- You **don’t make clear** what **minimum required fields** are for an “operational” user (esp. for field agents).
+
+**Grade: A- for backend correctness, C+ for lifecycle clarity**
+
+Backend logic is solid; product/lifecycle semantics are fuzzy.
+
+---
+
+## 2. Authentication & Session Handling
+
+### 2.1 Login (`/auth/login`)
+
+- Supabase handles the **password/auth**.
+- You:
+  - Validate credentials via `supabase_auth.sign_in`.
+  - Fetch local `User` by `auth_user.id`.
+  - Enforce `user.is_active`.
+  - Audit both success and failure.
+  - Rate limit to 10/min per IP.
+
+**What’s good**
+
+- **Separation** of auth vs business user.
+- **Audit logging** is properly used.
+- **Rate limiting** is in place.
+
+**What’s bad**
+
+- If the **local user doesn’t exist**, you 404 `"User profile not found"`.
+  - This is technically correct but leaks that the Supabase account exists.
+- No consistent **lockout strategy** for repeated failed logins (rate limiting helps, but doesn’t give feedback to admins).
+- All auth is via email/password; no clear support for **passwordless** or **SSO** (which is fine for now, but in 2025, you’ll get asked).
+
+**Grade: B+**
+
+Solid, but could be more hardened and explicit on edge cases.
+
+---
+
+### 2.2 Token → Current User (`get_current_user` / `get_current_active_user`)
+
+- You validate JWT with Supabase, then fetch `User` from DB.
+- `get_current_active_user` rejects inactive accounts.
+
+**What’s good**
+
+- Clean, simple, and correct glue logic.
+- You centralize this in `deps.py` and reuse it.
+
+**What’s bad**
+
+- No caching or optimization — not needed yet, but something you’ll feel at scale.
+- If Supabase is slow, your API is slow; there’s no fallback or short-circuit for already-known-good tokens (frontends should handle refresh, but still).
+
+**Grade: A-**
+
+Clean implementation. Nothing egregious here.
+
+---
+
+## 3. User Profile Modeling & Management
+
+### 3.1 Data Model (`User`)
+
+- `User` model is **rich**:
+  - Org membership: `client_id` / `contractor_id`.
+  - Role and `status`, `is_active`.
+  - Identity/contact, health & safety, PPE, geo-location, metadata.
+
+**What’s good**
+
+- This is an **excellent domain model** for a field-ops platform.
+- Proper use of JSONB for flexible health and PPE info.
+- Computed properties for `full_name`, `first_name`, `last_name` avoid duplicating fields.
+
+**What’s bad**
+
+- `status` vs `is_active` is **not clearly defined** as a state machine:
+  - `invited`, `pending_setup`, `active`, `suspended` exist on paper.
+  - In code, only `active`/`suspended` have strong behavior (both mapped to `is_active`).
+- You risk using `status` as a “label” instead of a **strictly enforced lifecycle**.
+- Health/PPE/location completeness is computed but **not enforced anywhere**.
+
+**Grade: A for modeling, C+ for state semantics**
 
 ---
 
-# Weaknesses / Problems
+### 3.2 Profile Endpoints & Permissions
+
+From `profile.py` + `ProfileService`:
 
-## 1. Self‑registration as `platform_admin`
+- `GET /profile/me` returns:
+  - Basic info, health, PPE, location, counts, completion status.
+- `ProfileService.get_profile_permissions`:
+  - Self vs admin vs org-admin vs managers vs field-agents.
+  - Very granular booleans: edit/view rights per section.
 
-- `POST /auth/register` creates every self‑registered user as:
-  - `role = "platform_admin"`
-  - `is_active = True`
-  - `status = "invited"` (but effectively usable)
-- This is **dangerous in production**. Anyone hitting `/auth/register` becomes the highest‑privilege user.
+**What’s good**
 
-**Impact**  
-- Extremely high risk: if `/auth/register` is exposed, you’ve essentially got open platform‑admin account creation.
+- This is **surprisingly mature**:
+  - You’ve thought carefully about **who can edit what**.
+  - Good use of `ProfilePermissions`.
+- `check_edit_permission` checks shared projects for managers/dispatchers vs field agents, which is realistic.
 
-## 2. Status semantics are confusing / inconsistent
+**What’s bad**
 
-- For self‑registration:
-  - Status is set to `"invited"` while the user is immediately active and logged in.
-- For invitation acceptance:
-  - Status is set to `"active"`.
-- `login` uses only `is_active`, not `status`, so:
-  - A user with `status="invited"` but `is_active=True` can still log in.
-- The `pending_setup` state is referenced in docs but I don’t see it enforced in this flow.
+- The **self-service edit endpoints** aren’t fully visible here, so it’s hard to confirm that:
+  - Every update path consistently uses `ProfilePermissions`.
+  - There’s no bypass via some other admin or service endpoint.
+- No clear, enforced **“profile completion required before X”** rules.
 
-**Impact**  
-- Harder to reason about real lifecycle states (“invited but not registered”, “registered but not set up profile”, etc).
-- Tooling and analytics relying on `status` may be incorrect.
+**Grade: B+**
 
-## 3. RBAC implementation is only partially used
+Model and thinking are strong; enforcement is not fully visible so I can’t give an A.
 
-- `core/permissions.py` defines `ROLE_PERMISSIONS` and `has_permission`, but:
-  - I don’t see route‑level checks using `has_permission("role", "permission")`.
-  - Instead, some endpoints hand‑code role logic (e.g., profile and user service).
-- This creates **duplication** and **risk of drift** between the central RBAC map and actual guards.
+---
 
-## 4. Suspended vs active inconsistencies at the auth provider
+## 4. Admin User Management (Roles, Status, Organizations)
 
-- `change_user_status` sets local `is_active` based on `status`, but:
-  - Supabase Auth account remains active; they can still get a valid token with correct password.
-  - You block them at the backend (`get_current_active_user`), which is good, but:
-    - You still incur auth load and leak some information (“account exists, but inactive”).
+### 4.1 Role-Based Access Control (`AppRole`, `ROLE_PERMISSIONS`)
 
-**Impact**  
-- Functionally safe at API level but not enforced at the auth provider.
-- Not necessarily a bug, but security‑grade hardening could require aligning Supabase user’s `blocked`/`app_metadata` flags.
+- You define roles + permission strings in a central module.
+- There is a `has_permission` helper; some endpoints use decorators like `@require_permission("manage_org_users")`.
 
-## 5. Inconsistent or legacy fields
+**What’s good**
 
-- In `accept_invitation`, you set `activated_at=datetime.now(timezone.utc)`, yet the `User` model comments say:
-  - `invited_at` and `activated_at` were removed and tracked in `user_invitations`.
-- If the DB column really is gone, this would fail at runtime; if it’s still there, comments are outdated and confusing.
+- **Centralized RBAC map** is the right approach.
+- Permissions are described at a nice level of granularity.
 
-## 6. Missing UX‑driven checks around profile completeness
+**What’s bad**
 
-- You compute `completion_status` in `ProfileService.calculate_profile_completion`, but:
-  - I haven’t seen it enforced anywhere (e.g., blocking certain actions until profile is complete).
-- Users might stay in a partially configured state while still getting full access, depending on role.
+- In practice, **logic is split**:
+  - Some code uses `@require_permission`.
+  - Some uses manual role checks (`if current_user.role == 'platform_admin'`, etc.).
+- This makes the **permission model fragile**:
+  - A change in `ROLE_PERMISSIONS` doesn’t necessarily update all behaviors.
+  - Docs and code can easily diverge.
 
-## 7. Supabase helper edge cases
+**Grade: B-**
 
-- `SupabaseAuth.sign_out` ignores the `access_token` parameter and just calls `self.client.auth.sign_out()` — works but:
-  - For multi‑session scenarios, you might want to specifically revoke that token.
-- `update_user` sets session using the same access token as both access and refresh token (`set_session(access_token, access_token)`), which may not align perfectly with Supabase’s model.
-  - Could be fine but is brittle if Supabase changes expectations.
+Right structure, incomplete application. For a production system, I’d call this “rough but usable”.
 
 ---
 
-# What Needs Changing Right Away (High Priority)
-
-1. **Stop self‑registration as platform admin**
-   - Change `register` flow so:
-     - Either:
-       - Self‑registration is disabled entirely in production, and all user creation goes through invitation / admin flows.
-       - Or: Self‑registered users get a **limited role** (e.g., `client_admin` for a new tenant, or `field_agent` for a specific app) with a safer onboarding path.
-     - Explicitly control who can become `platform_admin` via internal processes only.
-
-2. **Clarify and normalize `status` & `is_active`**
-   - Decide on a consistent lifecycle like:
-     - `invited` → `pending_setup` → `active` → `suspended`.
-   - Enforce:
-     - `invited` and `pending_setup` users should either:
-       - Not be able to log in, or
-       - Be restricted to a setup flow only.
-   - Ensure `register` sets `status` appropriately (likely `active` or `pending_setup`, not `invited`).
-
-3. **Wire route‑level checks to RBAC table**
-   - For endpoints that represent specific actions (e.g., manage users, manage projects, assign tickets):
-     - Use `has_permission(current_user.role, "<permission_name>")` instead of hard‑coding role checks everywhere.
-   - This will:
-     - Keep behavior consistent with `ROLE_PERMISSIONS`.
-     - Make it easier to adjust permissions centrally.
-
-4. **Confirm `activated_at` / legacy fields**
-   - Either:
-     - Remove `activated_at=...` from `accept_invitation` if the column no longer exists.
-     - Or: Update `User` model + comments to reflect actual DB schema.
-   - Inconsistency here can cause subtle migration/runtime issues.
+### 4.2 User Admin Operations (`UserService`, `/users` endpoints)
+
+- `UserService`:
+  - `check_update_permission` handles who can update whom, and what.
+  - `update_user` tracks detailed change diffs.
+  - `change_user_status` + `change_user_role` encapsulate logic.
+- `/users/{user_id}/status` and `/users/{user_id}/role` endpoints exist and use these services with audit logging.
+
+**What’s good**
+
+- **Service layer is well done**:
+  - Clear separation: endpoint → service → DB.
+  - Fine-grained permission checking.
+  - Audit logs on changes, with old/new values.
+- **Org-based scoping** (client/contractor admin cannot promote to platform_admin and cannot change org) is exactly what you want.
+
+**What’s bad**
+
+- There’s still an opportunity to move more of the **role/permission logic into a single coherent RBAC layer**, rather than repeating patterns across `UserService` and `ProfileService`.
+- No **role history tracking** beyond an audit log. That’s fine for early stage, but not “enterprise ready”.
+
+**Grade: B+**
+
+Much better than your own doc suggests (you gave yourself F there). From a backend perspective, it’s “good but not fully systematized”.
 
 ---
 
-# Medium‑Priority Improvements
+## 5. Security Posture
+
+**What’s strong**
+
+- Supabase Auth handles passwords and token issuance.
+- No password storage in your own DB.
+- Audit logging is used for:
+  - Auth events (register, login).
+  - Role/status changes.
+- Rate limiting on critical endpoints.
 
-- **Supabase sync on suspension**
-  - Optionally, when suspending a user:
-    - Update their Supabase user (e.g., `user_metadata` or `app_metadata`) to mark them as suspended, or use any “blocked” mechanism available.
-  - This prevents them from even getting a token.
+**What’s weak**
 
-- **Enforce profile completeness for certain roles**
-  - For roles like `field_agent`:
-    - Require certain profile sections (PPE, emergency contacts, basic info) to be complete before:
-      - Accepting field tasks.
-      - Being assigned to risky operations.
-  - Gate important endpoints behind `completion_status` checks.
+- **Hardcoded operational secrets/constraints** (platform admin email) in code.
+- Incomplete alignment between **Supabase account status** and local `status`/`is_active`:
+  - Suspended at API level, but still able to authenticate at Supabase and get a token.
+  - This is *okay* as long as you always use `get_current_active_user` and never trust Supabase ID alone, but it’s not ideal for a “locked” account.
+- Some behaviors (like 404 on “User profile not found” after a successful auth) leak information about account existence.
 
-- **Lockout / abuse protection**
-  - You have rate limiting, which is good.
-  - Consider additional measures:
-    - Optional account lockout after N failed logins.
-    - Tracking login IP / device in metadata.
+**Grade: B-**
 
-- **Better use of `ProfilePermissions`**
-  - Ensure all profile update endpoints (not just `GET /me`) consistently respect `ProfilePermissions` booleans to prevent accidental over‑editing by org roles.
+Better than typical side-projects, but not yet “security-audited product”.
 
 ---
 
-# Low‑Priority / Nice to Have
+## 6. Developer Experience & Consistency
 
-- Use `ROLE_PERMISSIONS` not just for “system actions” but also for UI hints, so the frontend can hide/show features based on the same central map.
-- Add tests for:
-  - `UserService.check_update_permission` across roles + org boundaries.
-  - `ProfileService.get_profile_permissions` permutations (self vs admin vs manager).
-  - Status transitions and how they affect `is_active` and login behavior.
+**What’s good**
+
+- Services (`UserService`, `ProfileService`, `InvitationService`) centralize business logic fairly well.
+- Models, schemas, and endpoints are reasonably consistent.
+- Good logging patterns.
+
+**What’s bad**
+
+- Some business rules (status semantics, RBAC) are spread across:
+  - `UserService`
+  - `ProfileService`
+  - Endpoint decorators
+  - Comments and docs
+- You do not have a **single place** that clearly defines:
+  - User lifecycle state machine.
+  - Role/permission matrix (you’re close, but not fully coherent).
+- Docs and code disagree in a few places (e.g., your markdown says “role management not implemented” but the code clearly has it).
+
+**Grade: C+/B-**
+
+The code is better than your docs indicate, but cohesion is not tight yet.
 
 ---
 
-# “Grade” of Your Work
+## Overall “Brutal” Grades
+
+- **Account creation & invitation**: A- (logic), C+ (lifecycle clarity & bootstrap config) → overall **B+**
+- **Authentication & token handling**: **B+**
+- **Profile modeling & permissions**: A (model), B (enforcement) → overall **B+**
+- **Admin user management (roles/status/org)**: **B+**
+- **RBAC framework & usage**: **B-**
+- **Security posture (for a pre-production system)**: **B-**
+- **Production-readiness (for a paying customer SaaS)**: **B-/C+**
 
-If I had to assign letter grades per area:
+You are **well above “toy project”** level. The architecture is thoughtful; the main gaps are:
 
-- **Overall architecture (auth vs profile separation, use of services)**: **A**
-- **RBAC design (roles, permissions, hierarchy)**: **B+**
-  - Solid structure, but not fully applied via `has_permission` yet.
-- **Onboarding flows (invitation, profile creation)**: **A‑**
-  - Invitation flow is strong; self‑registration is the main issue.
-- **Security hardening (roles for self‑registration, status semantics, suspension)**: **C**
-  - The platform_admin self‑registration is a serious concern and should be fixed before production exposure.
+- Hardcoded & opaque bootstrap for platform admin.
+- Incomplete, poorly enforced user lifecycle state machine.
+- RBAC that is partly centralized, partly duplicated.
 
 ---
 
-If you’d like, next step I can propose **concrete code changes** (files + specific modifications) to:
-- Fix the self‑registration role.
-- Normalize statuses and `is_active`.
-- Introduce `has_permission` checks for a couple of key endpoints as a pattern.
+## If You Want Hard “Fix Now” Priorities
+
+1. **Remove hardcoded platform admin email from code; move to config/env + document bootstrap process.**
+2. **Define and enforce a real user lifecycle state machine** (`invited` → `pending_setup` → `active` → `suspended`), and ensure all flows respect it.
+3. **Standardize RBAC checks**:
+   - Make a single decorator / helper that uses `ROLE_PERMISSIONS + per-resource rules`, and use that everywhere.
+4. **Align suspension with Supabase** (at least by marking metadata, ideally blocking login).
+
+If you want, I can next propose *specific code edits* (file + change), ordered by risk/impact, to push this from B/B- into A- territory.

src/app/api/v1/auth.py

@@ -29,18 +29,19 @@ async def register(request: Request, response: Response, user_data: UserCreate,
     **SECURITY MODEL:**
     - Self-registration is DISABLED for regular users (must use invitation flow)
     - Platform admin creation requires OTP verification sent to authorized email
-    - Only lewiskimaru01@gmail.com can receive platform admin OTPs
+    - Configurable via PLATFORM_ADMIN_EMAIL environment variable
     
     **Process:**
     1. Submit registration request
-    2. OTP sent to lewiskimaru01@gmail.com
+    2. OTP sent to configured admin email (PLATFORM_ADMIN_EMAIL)
     3. Use OTP to verify via /otp/verify-public endpoint
     4. After OTP verification, account is created as platform_admin
     
     **Note:** Regular users (field agents, managers, etc.) must be invited by admins.
     """
-    # Security check: Only allow platform admin registration for authorized email
-    PLATFORM_ADMIN_EMAIL = "lewiskimaru01@gmail.com"
+    # Get platform admin email from config (can be overridden via environment variable)
+    from app.config import settings
+    PLATFORM_ADMIN_EMAIL = settings.PLATFORM_ADMIN_EMAIL
     
     # Check if this is an attempt to create a platform admin account
     # Platform admin accounts can only be created via OTP verification

src/app/api/v1/documents.py

@@ -19,6 +19,7 @@ from app.schemas.document import (
 )
 from app.services.media_service import StorageService
 from app.services.audit_service import AuditService
+from app.core.permissions import require_permission, require_any_permission
 from datetime import datetime
 import logging
 import json
@@ -32,6 +33,7 @@ router = APIRouter(prefix="/documents", tags=["Document Management"])
 # ============================================
 
 @router.post("/upload", response_model=DocumentResponse, status_code=status.HTTP_201_CREATED)
+@require_permission("upload_documents")
 async def upload_document(
     file: UploadFile = File(...),
     entity_type: str = Form(...),
@@ -159,6 +161,7 @@ async def upload_document(
 
 
 @router.get("/{entity_type}/{entity_id}", response_model=DocumentListResponse)
+@require_permission("view_documents")
 async def get_entity_documents(
     entity_type: str,
     entity_id: UUID,
@@ -298,6 +301,7 @@ async def update_document_metadata(
 
 
 @router.delete("/id/{document_id}", status_code=status.HTTP_204_NO_CONTENT)
+@require_permission("upload_documents")  # Same permission as upload (can manage own documents)
 async def delete_document(
     document_id: UUID,
     request: Request,

src/app/config.py

@@ -21,6 +21,9 @@ class Settings(BaseSettings):
     SUPABASE_KEY: str
     SUPABASE_SERVICE_KEY: str
 
+    # Security & Access Control (REQUIRED)
+    PLATFORM_ADMIN_EMAIL: str  # Email for platform admin OTP verification - must be set in .env
+    
     # Optional External Services
     CLOUDINARY_CLOUD_NAME: Optional[str] = None
     CLOUDINARY_API_KEY: Optional[str] = None

src/app/core/permissions.py

@@ -1,5 +1,29 @@
 """
 Role-Based Access Control (RBAC) Definitions
+
+This module provides centralized permission management for all roles.
+All route handlers should use @require_permission or @require_role decorators
+to enforce consistent access control.
+
+Usage Examples:
+    from app.core.permissions import require_permission, require_role, AppRole
+    
+    @router.get("/users")
+    @require_permission("view_users")
+    async def list_users(current_user: User = Depends(get_current_active_user)):
+        ...
+    
+    @router.delete("/users/{id}")
+    @require_role(AppRole.PLATFORM_ADMIN)
+    async def delete_user(current_user: User = Depends(get_current_active_user)):
+        ...
+
+Permission Categories:
+    - User Management: view_users, manage_org_users, invite_users
+    - Documents: view_documents, upload_documents
+    - Projects: manage_projects, create_tickets
+    - Financial: view_payroll, approve_expenses
+    - Reports: view_reports, export_reports
 """
 from enum import Enum
 from typing import List, Dict, Callable
@@ -11,7 +35,16 @@ logger = logging.getLogger(__name__)
 
 
 class AppRole(str, Enum):
-    """Application roles"""
+    """
+    Application Roles
+    
+    Hierarchy (highest to lowest):
+    1. PLATFORM_ADMIN - Full system access
+    2. CLIENT_ADMIN / CONTRACTOR_ADMIN - Organization-level admin
+    3. SALES_MANAGER / PROJECT_MANAGER - Department managers
+    4. DISPATCHER - Operations coordinator
+    5. FIELD_AGENT / SALES_AGENT - Individual contributors
+    """
     PLATFORM_ADMIN = "platform_admin"
     CLIENT_ADMIN = "client_admin"
     CONTRACTOR_ADMIN = "contractor_admin"
@@ -23,6 +56,8 @@ class AppRole(str, Enum):
 
 
 # Role permissions mapping
+# Platform admin has "*" (all permissions)
+# All other roles have explicit permission lists
 ROLE_PERMISSIONS: Dict[AppRole, List[str]] = {
     AppRole.PLATFORM_ADMIN: ["*"],  # All permissions
     AppRole.CLIENT_ADMIN: [

src/app/models/user.py

@@ -18,6 +18,33 @@ class User(BaseModel):
     
     Authentication: Supabase Auth (auth.users table)
     This table stores business profile and authorization data
+    
+    USER LIFECYCLE STATE MACHINE:
+    ┌─────────────────────────────────────────────────────────────────┐
+    │ Status Flow:                                                     │
+    │                                                                  │
+    │ invited → pending_setup → active → suspended                    │
+    │    ↓           ↓            ↓          ↓                         │
+    │  (invited) (setup req) (operational) (disabled)                │
+    └─────────────────────────────────────────────────────────────────┘
+    
+    Status Definitions:
+    - invited: User invited but hasn't accepted/registered yet
+      (Used in invitation flow only, before user_invitations.accepted_at)
+    
+    - pending_setup: User accepted invitation but profile incomplete
+      (Reserved for future: require certain fields before full access)
+    
+    - active: Fully operational user with complete access
+      (Default after invitation acceptance, primary operational state)
+    
+    - suspended: Account temporarily disabled (is_active=False)
+      (Can be reactivated by admin, preserves all data)
+    
+    Note: is_active field controls actual access:
+    - active/pending_setup → is_active=True (can login)
+    - suspended → is_active=False (blocked at API level)
+    - invited → varies (typically False until acceptance)
     """
     __tablename__ = "users"