permissions

This table stores the normalized catalog of permissions used by DirtView’s RBAC system. Permissions are the atomic access capabilities that roles are built from.

Domain: RBAC

Scope: Global catalog

Status: Proposed

Last Updated: 11 Apr 2026

Mutable: Low-change

Primary Owner: RBAC / Core API

RLS Applies: Usually not tenant-scoped

Client Facing: No direct exposure

Purpose

The purpose of this table is to define the reusable permission catalog that roles can be mapped to. This allows DirtView to express access rules at a granular level instead of hardcoding everything into role names.

What this table does

Defines all atomic permissions used across the platform
Supports company, project, and module-level access design
Acts as the canonical permission dictionary for roles
Allows future expansion without redesigning role structures

Why this table is defined

DirtView’s access model is too rich to rely only on named roles. The system needs permissions such as “manage employees,” “upload drawings,” “view RFIs,” and “edit project members” to be modeled explicitly and mapped to roles.

Columns

Column	Type	Required	Description	Example
`id`	uuid	Yes	Primary key for the permission record	`perm_001`
`code`	text	Yes	Stable machine-readable permission key	`drawings.upload`
`name`	text	Yes	Human-readable permission name	`Upload Drawings`
`scope`	text	Yes	Permission level such as company, project, or module	`module`
`module_key`	text	No	Optional module grouping for the permission	`drawings`
`description`	text	No	Plain-English description of what this permission allows	`Allows the user to upload drawing PDFs and create new drawing sets`
`created_at`	timestamptz	Yes	Creation timestamp	`2026-04-01 08:00:00+00`

Relationships

id is referenced by role_permissions.permission_id
module_key may align conceptually with project_module_access.module_key

How it is used

Seeded as part of the RBAC baseline
Mapped to roles through role_permissions
Used by backend authorization logic to resolve effective access
Can be used by admin UI to explain what each role can do

Access and security

This table should be treated as system configuration
Permission codes should be stable and not casually renamed
Changes here can affect authorization broadly and should be reviewed carefully

Example scenarios

Scenario 1: Employee management permission

employees.manage allows a role to create, update, or deactivate employee records.

Scenario 2: Drawings upload permission

drawings.upload allows the upload of drawing source files.

Scenario 3: Project user management permission

projects.members.manage allows project membership changes.

Notes and assumptions

Keep permission code values stable across environments
Prefer additive permissions over ambiguous role-only logic
Document each permission clearly so tenant admins understand role behavior