user_company_roles
This table assigns company-level roles to tenant memberships. It determines the default role a user has within a tenant before any project-specific override is applied.
Purpose
The purpose of this table is to define the company-level default role for a tenant member. It forms the baseline of the 3-level DirtView access model: company, project, and module.
What this table does
- Assigns one or more roles to a tenant membership at company scope
- Defines baseline access before project-level overrides
- Connects tenant membership identities to the reusable role catalog
Why this table is defined
DirtView’s access model requires a company-level default role. That role cannot live only in the JWT or only in the user profile because it is tenant specific and must be queryable and auditable in the database.
Columns
| Column | Type | Required | Description | Example |
|---|---|---|---|---|
membership_id |
uuid | Yes | Tenant membership receiving the role | membership_123 |
role_id |
uuid | Yes | Role assigned at company level | role_pm |
assigned_by |
uuid | No | User who assigned the role | user_admin_001 |
assigned_at |
timestamptz | Yes | When the role was assigned | 2026-04-05 11:00:00+00 |
Relationships
- membership_id → tenant_memberships.id
- role_id → roles.id
- Project-level override logic is handled separately in
user_project_roles
How it is used
- Resolved during authorization to determine baseline company access
- Used when deciding whether a user can manage employees, create projects, or administer tenant-level features
- Used as the fallback when no project override exists
Access and security
- Role assignment changes should be restricted to authorized admins
- Changes to this table should be audited
- Constraints should prevent duplicate identical assignments where appropriate
Example scenarios
Scenario 1: New tenant admin
When the first customer admin is onboarded, a company-level Admin role is assigned here.
Scenario 2: Standard foreman user
A field user is assigned the Foreman role at company level and inherits that baseline across projects unless overridden.
Scenario 3: Viewer baseline
A user is assigned Viewer company-wide, then elevated on one project through project-specific role assignment.
Notes and assumptions
- This table stores assignments, not role definitions
- Project-level overrides should take precedence where applicable
- Depending on business rules, you may allow one or multiple company-level roles