1In one sentence#

The Access Control module (RBAC — Role-Based Access Control) is LumosCRM's security backbone — it defines roles, the fine-grained permissions behind every action in every module, and who holds what, so each team member sees and does exactly what their job requires and nothing more.

Every "can this user do this?" decision across the entire CRM ultimately traces back here.

2Who it's for#

Role	What they get
Workspace owners / administrators	Full control over roles, permissions, and who's assigned to them.
Compliance & security	Assurance that access is least-privilege, auditable, and enforced everywhere.
Every user	The right, role-appropriate experience — irrelevant and unauthorised actions simply aren't shown.

3The core idea: granular permissions, grouped into roles#

LumosCRM doesn't gate access with a few coarse "admin / staff" switches. Instead, every action in every module has its own permission — clients.record.view, invoices.items.create, vendors.contracts.delete, events.budget.update, and so on. Those fine-grained permissions are grouped into roles (e.g. "Concierge," "Finance," "Compliance Officer," "Agency Owner"), and users are assigned roles.

   PERMISSIONS               ROLES                  USERS
   clients.record.view  ┐
   clients.record.edit  ├──▶  "Concierge"   ──┐
   requests.tasks.*     ┘                      ├──▶  Alex (Concierge)
   invoices.record.*    ┐                      │
   invoices.financial.* ├──▶  "Finance"   ─────┤──▶  Sam (Finance + Compliance)
   reports.record.*     ┘                      │
   documents.record.*   ───▶  "Compliance" ────┘

A user can hold several roles, and can also be granted individual permissions directly for fine adjustments.

4Capabilities at a glance#

Capability	What it means
Roles	Create, edit, and delete roles, and set exactly which permissions each one grants.
Permissions	A complete catalogue of fine-grained, per-action permissions across all modules.
Assign roles to users	Give a user one or more roles.
Direct permissions	Grant a user individual permissions beyond their roles.
Owner bypass	A top-level "Agency Owner"-style role bypasses checks so administrators are never locked out.
Enforced everywhere	Permissions gate both the backend (routes/controllers) and the frontend (menus, tabs, buttons).
The Access Control screen	A single admin UI to manage all of the above.

5Enforced on both sides — no security through hiding#

Permissions are enforced in two places at once:

Backend: every route and controller action is gated by its permission. A request a user isn't entitled to make is rejected server-side (with a proper 403 page), regardless of what the UI shows.
Frontend: menus, tabs, and action buttons the user lacks permission for are simply not rendered — so the interface is clean and role-appropriate, not cluttered with things they can't use.

This belt-and-braces approach means the UI is tailored and the data is genuinely protected — hiding a button is never the only line of defence.

6The Access Control screen#

A dedicated admin area (reached from Settings → Roles) lets administrators:

Browse and manage roles and the permissions each grants.
Browse the full permissions catalogue.
Open a user's access view to assign/sync/revoke roles and grant direct permissions.

7Security model highlights#

Least privilege by default: users get only what their roles grant.
Owner safeguard: a super-admin ("Agency Owner") role bypasses individual checks so the workspace can always be administered — but this bypass is deliberate and visible, and it does not override per-record data-scoping rules.
Works with data scoping: RBAC controls what actions a user can take; per-user data scoping (self-scoping) controls which records they can take them on. Together they give both functional and row-level security.

8Permissions reference (the module's own)#

Action	Permission
View roles	`rbac.roles.view`
Create / edit / delete roles, sync role permissions	`rbac.roles.manage`
View permissions	`rbac.permissions.view`
Create / edit / delete permissions	`rbac.permissions.manage`
View a user's access, assign / sync / revoke roles, grant direct permissions	`rbac.users.assign`

Every other module defines its own <module>.<section>.<action> permissions; this module is where they're organised into roles and assigned to people.

9Use cases & scenarios#

Use case A — A focused concierge role#

An admin creates a Concierge role with permission to view clients, manage requests and tasks, and log communications — but not to issue invoices or manage roles. Anyone assigned it gets a clean, focused CRM.

Use case B — Separation of duties#

Finance can issue and void invoices but can't change client KYC; Compliance can manage KYC and consents but can't touch billing. RBAC makes the separation real and enforced.

Use case C — A one-off exception#

A senior concierge needs to export reports just this quarter. Rather than change the whole role, the admin grants them the reports.record.export permission directly.

10Glossary#

Term	Meaning
Permission	The right to perform one specific action (e.g. `invoices.record.issue`).
Role	A named bundle of permissions (Concierge, Finance, Owner…).
Assignment	Giving a user one or more roles.
Direct permission	A permission granted to a user outside their roles.
Owner bypass	The super-admin role that isn't blocked by individual permission checks.
Data scoping	The complementary rule controlling which records a user can act on.

This document describes the Access Control module as currently built: granular per-action permissions grouped into roles and assigned to users, enforced on both backend and frontend, complemented by per-record data scoping.