roles

This table stores the role definitions used by a tenant for access control. It includes the default system roles and any tenant-customized roles.

Domain: RBAC

Scope: Tenant

Status: Proposed

Last Updated: 11 Apr 2026

Mutable: Yes

Primary Owner: RBAC / Core API

RLS Applies: Yes

Client Facing: Indirectly

Purpose

The purpose of this table is to define named access roles within a tenant, such as Admin, Project Manager, Superintendent, Safety Manager, Foreman, and Viewer, along with any future custom roles.

What this table does

Stores role definitions per tenant
Supports seeded default roles and future custom roles
Provides the role objects that permission mappings attach to
Acts as a reusable access-control building block across company and project contexts

Why this table is defined

DirtView requires structured RBAC across company, project, and module levels. Roles are the human-readable and manageable way to bundle permissions into meaningful job-oriented access groups.

Columns

Column	Type	Required	Description	Example
`id`	uuid	Yes	Primary key for the role record	`role_001`
`tenant_id`	uuid	Yes	Tenant that owns this role definition	`tenant_001`
`code`	text	Yes	Machine-readable role key	`project_manager`
`name`	text	Yes	Human-readable display name	`Project Manager`
`description`	text	No	Optional explanation of the role	`Can manage project members and core workflows`
`is_system_default`	boolean	Yes	Whether this role is one of the seeded default roles	`true`
`is_editable`	boolean	Yes	Whether tenant admins can modify this role definition	`false`
`created_at`	timestamptz	Yes	Creation timestamp	`2026-04-01 08:00:00+00`
`updated_at`	timestamptz	Yes	Last update timestamp	`2026-04-11 09:15:00+00`

Relationships

tenant_id → tenants.id
id is referenced by user_company_roles.role_id
id is referenced by project-level role assignment tables
id is referenced by role_permissions.role_id

How it is used

Seeded during tenant onboarding
Assigned to memberships at company level
May be reused at project level as an override
Combined with permission tables to determine effective access

Access and security

Tenant admins may manage some roles, depending on product rules
System default roles should usually be protected from accidental deletion
Role changes should be audited because they affect authorization

Example scenarios

Scenario 1: Tenant provisioning

DirtView seeds Admin, Project Manager, Superintendent, Safety Manager, Foreman, and Viewer roles for the new tenant.

Scenario 2: Custom role

A tenant later creates a custom role such as “Document Coordinator.”

Scenario 3: Project override

A user with Viewer at company level may be assigned Project Manager for one project using the same role table.

Notes and assumptions

Roles are definitions only, not assignments
Actual permission logic comes from permission mapping tables
Keep code stable even if name changes