RBAC Matrix

Status: ✅ Active
Roles source: roles.md · ADR-005Last updated: 2026-04-17

This document defines who can do what across all Busflow entities. It is the source of truth for Hasura permission rules and NestJS @RequiresCapability() guards.

Design Principles

Tenant isolation first. Every query and mutation filters by x-hasura-tenant-id. No role bypasses this (except busflow_staff).
Three core roles. MANAGER, DISPATCHER, DRIVER. Additional roles (OWNER, VIEWER) are deferred to V1.1.
Additive capabilities. user_access_grants extends a role — never restricts. MANAGER implicitly holds all capabilities.
Keep it simple. Start with coarse permissions. Refine column-level or row-level restrictions when a real use case demands it.

Notation

Symbol	Meaning
✅	Full access (CRUD)
📖	Read-only
✏️	Create + Read + Update (no delete)
🔒	No access
⚡	Via Hasura Action only (business logic enforced server-side, no direct table mutation)
🧩	Requires additional capability grant

Backoffice Schema

Capability Gate = the capability required for a non-MANAGER role to access. If the role already has the capability as a base grant (per roles.md), no additional user_access_grants entry is needed. DISPATCHER base capabilities: DISPATCH, BOOKING_MGMT, FLEET_MGMT.

Entity	MANAGER	DISPATCHER	DRIVER	Capability Gate	Notes
`operators`	✏️	📖	🔒	—	MANAGER edits company settings. No delete (lifecycle via `status`). Must omit `platform_fee_config` and `subscription_tier` from MANAGER update (column-level).
`operator_settings`	✏️	📖	🔒	—	1:1 with operator. No delete.
`operator_integrations`	✏️	📖	🔒	—	Mollie, DATEV, DPA connections. No delete (lifecycle via `status`).
`tenant_subscriptions`	✏️	🔒	🔒	—	Billing plan state. `busflow_staff` provisions. Must omit `plan_id` and `status` from MANAGER update (column-level). The `BillingModule` handles state mutations.
`user_tenant_assignments`	✅	🔒	🔒	—	Only MANAGER manages user access.
`user_access_grants`	✅	🔒	🔒	—	Only MANAGER grants capabilities.
`tour_templates`	✅	✏️	🔒	`DISPATCH`	Base DISPATCHER capability.
`tour_departures`	✅	✏️	📖	`DISPATCH`	Drivers see their assigned departures (row-scoped).
`boarding_points`	✅	✏️	📖	`DISPATCH`	Part of departure setup. Drivers see stop info.
`costing_sheets`	✅	📖	🔒	—	Dispatchers need read access for margin context when quoting. Full financial detail requires 🧩 `FINANCIAL_REPORTS`.
`price_matrices`	✅	📖	🔒	—	Dispatchers need published prices for booking management.
`crew_members`	✅	📖	🔒	`CREW_MGMT`	MANAGER CRUDs. Dispatchers read for assignments (🧩 `CREW_MGMT` for write).
`crew_qualifications`	✅	📖	🔒	`CREW_MGMT`	Dispatchers read for dispatch validation.
`crew_absences`	✅	✏️	🔒	`CREW_MGMT`	Dispatchers create/approve (🧩 `CREW_MGMT` required for write).
`vehicles`	✅	✏️	📖	`FLEET_MGMT`	Base DISPATCHER capability. Drivers see assigned vehicle.
`vehicle_inspections`	✅	✏️	🔒	`FLEET_MGMT`	Base DISPATCHER capability.
`suppliers`	✅	📖	🔒	—	Hotel/ferry/guide partners.
`allotments`	✅	📖	🔒	—	Inventory blocks.
`resellers`	✅	📖	🔒	—	Agency/corporate partners.
`charter_quotes`	✅	✏️	🔒	`DISPATCH`	B2B quotes.
`person_profiles`	✅	✏️	📖	`BOOKING_MGMT`	Base DISPATCHER capability. Drivers see manifest names (row-scoped).
`notification_templates`	✅	📖	🔒	—	Template config is MANAGER-only.
`change_events`	📖	📖	🔒	—	Audit trail. System-written. Drivers don't access Backoffice audits.

Commerce Schema

Entity	MANAGER	DISPATCHER	DRIVER	Capability Gate	Notes
`tour_offerings`	📖	📖	🔒	—	Created by system (on `TourDeparturePublished`). Read-only.
`bookings`	✅	✏️	📖	`BOOKING_MGMT`	Dispatchers manage bookings. Drivers see passenger count.
`passengers`	✅	✏️	📖	`BOOKING_MGMT`	Drivers see manifest names.
`tickets`	📖	📖	📖	—	System-issued. All roles read.
`seat_reservations`	✅	✏️	📖	`BOOKING_MGMT`	Dispatchers reassign seats.
`ancillaries`	✅	✏️	🔒	`BOOKING_MGMT`	Add-ons per booking.
`checkout_sessions`	📖	📖	🔒	—	System-managed payment flow. Read-only.
`payments`	📖	📖	🔒	`FINANCIAL_REPORTS`	Financial data.
`invoices`	📖	📖	🔒	`FINANCIAL_REPORTS`	System-generated. Read-only.
`financial_ledgers`	📖	🔒	🔒	`FINANCIAL_REPORTS`	Sensitive financial aggregation. 🧩 grant needed.
`tax_ledger_entries`	📖	🔒	🔒	`FINANCIAL_REPORTS`	Tax data. 🧩 grant needed.

Operations Schema

Entity	MANAGER	DISPATCHER	DRIVER	Capability Gate	Notes
`service_legs`	✅	✏️	⚡	`DISPATCH`	Drivers transition via Actions (`startServiceLeg`, `completeServiceLeg`). Dispatchers cancel via `cancelServiceLeg`.
`leg_assignments`	✅	✏️	📖	`DISPATCH`	Dispatchers assign crew. Drivers see own assignments.
`boarding_events`	📖	📖	⚡	—	Drivers create via offline sync. Read-only for workspace users.
`incidents`	✏️	✏️	⚡	—	Drivers create (offline). Dispatchers manage (acknowledge, assign, resolve via `takeOverIncident`, `resolveIncident`).
`issue_reports`	✏️	✏️	⚡	—	Drivers create via `createIssueReport`. Dispatchers link/resolve via `linkIssueReportToIncident`, `resolveIssueReport`.
`incident_issue_reports`	📖	✏️	🔒	—	Join table. Created by Actions.
`onboard_sales`	📖	✏️	⚡	—	Drivers create (offline sync). Dispatchers can void/refund.
`expense_receipts`	📖	✏️	⚡	—	Drivers submit. Dispatchers verify/reject (`verifyExpenseReceipt`, `rejectExpenseReceipt`).
`telemetry_points`	📖	📖	⚡	—	Drivers push GPS data (`POST /api/telemetry`). System-managed.
`route_waypoints`	📖	📖	📖	—	System-created via `TourDeparturePublished`. ETA updated by system.
`crew_duty_logs`	📖	📖	📖	—	System-populated. Phase 2 for write access.
`change_events`	📖	📖	🔒	—	Operations audit trail. System-written.

Communications Schema

Entity	MANAGER	DISPATCHER	DRIVER	Capability Gate	Notes
`conversations`	📖	📖	🔒	—	System-created for broadcast threads.
`messages`	📖	✏️	🔒	—	Dispatchers approve broadcasts, view message history.
`contacts`	📖	📖	🔒	—	System-managed (passenger-facing).
`channel_accounts`	✅	🔒	🔒	—	WhatsApp/Email provider config. MANAGER-only.

Public & Passenger Access

These roles operate outside the tenant RBAC system. They don't use user_tenant_assignments or x-hasura-tenant-id.

`anonymous` (Hasura public role)

The Hasura anonymous role serves unauthenticated frontends: the booking widget, landing page, and marketing site. The system scopes permissions by the operator's public slug or domain — no JWT required.

Entity	Access	Scope	Frontend
`tour_offerings`	📖	WHERE `status = 'PUBLISHED'` AND operator matched by public slug	Booking widget — tour catalog
`price_matrices`	📖	WHERE `status = 'PUBLISHED'` AND linked to public `tour_offering`	Booking widget — price display
`boarding_points`	📖	WHERE linked to published `tour_departure`	Booking widget — pickup selector
`seat_reservations`	📖	Availability count only (no passenger data)	Booking widget — seat picker
`bookings`	✏️	CREATE only (via Hasura Action `createBooking`)	Booking widget — checkout flow

NOTE

Booking widget tenant resolution: The widget identifies the operator via a public slug in the URL (e.g., book.busflow.de/reisebuero-mueller). The server resolves slug → tenant_id and applies it as the implicit filter. No x-hasura-tenant-id in the JWT — anonymous requests don't have JWTs.

`passenger` `[future]`

Passengers interact with booking-widget (pre-trip) and passenger portal (post-booking). Authentication is lightweight — email + booking code or magic link, not traditional login. The identity model (Nhost auth.users vs. standalone token service) is an open architectural decision — see roles.md §Passengers. A dedicated B2C auth specification will define token TTLs, flow diagrams, and Hasura role configuration.

Expected data scope (pending auth spec):

Entity	Access	Scope
`bookings`	📖	Own booking(s) only
`passengers`	📖	Own passenger record only
`tickets`	📖	Own tickets (QR code, Wallet pass)
`boarding_points`	📖	Linked to own booking's departure

Consumer ETA Tracking (token-secured, no auth)

GET /api/track/:tracking_token — no Hasura role. This is a standalone NestJS endpoint secured by a short-lived JWT tracking token (not a Hasura session). Returns vehicle position + ETA. See schema-operations.md §Consumer ETA Tracking.

NOTE

Why not a Hasura role? The tracking endpoint serves data from multiple schemas (Operations telemetry_points + route_waypoints) to unauthenticated passengers via a signed token. It's simpler and more secure as a dedicated NestJS route than as a Hasura permission on the anonymous role — the token carries the specific service_leg_id + passenger_id scope, and the response is a computed aggregate, not a raw table read.

Hasura Actions — Role Matrix

Actions enforce business logic server-side. The handler validates the requesting user's role and capabilities.

Action	MANAGER	DISPATCHER	DRIVER	Notes
`provisionTenant`	🔒	🔒	🔒	`busflow_staff` only
`startServiceLeg`	🔒	🔒	✅	Guard: active `LegAssignment` for requesting crew member
`completeServiceLeg`	🔒	🔒	✅	Guard: active `LegAssignment`
`cancelServiceLeg`	✅	✅	🔒	Guard: MANAGER required if boarding events exist
`takeOverIncident`	✅	✅	🔒	Dispatcher acknowledges + takes ownership
`resolveIncident`	✅	✅	🔒	Any DISPATCHER/MANAGER (no `assigned_to` check — shift handoff)
`createIssueReport`	✅	🔒	✅	Per schema: `x-hasura-role ∈ { DRIVER, MANAGER }`. Offline-capable via sync.
`linkIssueReportToIncident`	✅	✅	🔒	Dispatcher links report → incident
`resolveIssueReport`	✅	✅	🔒	Dispatcher resolves (OPEN only; IN_PROGRESS auto-resolves via inspection)
`verifyExpenseReceipt`	✅	✅	🔒	Dispatcher confirms OCR output
`rejectExpenseReceipt`	✅	✅	🔒	Dispatcher rejects with mandatory reason
`swapVehicle`	✅	✅	🔒	Guard: requires `FLEET_MGMT` capability (DISPATCHER base)
`upsertPricingConfig`	✅	⚡	🔒	Guard: requires premium `X-Hasura-Plan` (tier values TBD by product). Used to update `pricing_rules` on `tour_templates`.

Driver Data Scoping

Drivers access a narrow slice of data, scoped to their assignments:

Driver sees:
  tour_departures    WHERE id IN (leg_assignments.tour_departure_id WHERE crew_member_id = me)
  service_legs       WHERE id IN (my leg_assignments)
  boarding_events    WHERE service_leg_id IN (my legs)
  passengers         WHERE booking.tour_offering_id IN (my tour_offerings)
  boarding_points    WHERE tour_departure_id IN (my departures)
  vehicles           WHERE id IN (my leg_assignments.vehicle_id)

NOTE

Hasura row-level permissions implement this scoping. The x-hasura-user-id session variable resolves the driver's crew_member_id via crew_members.user_id, then filters through leg_assignments. This avoids exposing any data from other drivers' assignments or other tenants.

Platform Role: `busflow_staff`

Access	Scope
All tenant data	Cross-tenant `SELECT` (no `tenant_id` filter)
`provisionTenant` Action	Creates operators + seeds config
User management	Via Nhost Admin SDK
Audit trail	All mutations logged with `user_id` + `correlation_id`

WARNING

No direct table mutations. Busflow staff mutate via Actions only (enforced by Hasura permission rules). All staff actions generate change_events with scope = CONFIG.

Implementation Notes

Hasura role strategy: Start with 3 Hasura roles (manager, dispatcher, driver) mapping directly to user_tenant_assignments.default_role. Evaluate Hasura inherited roles during implementation if capability-based granularity is needed at the Hasura layer (see ADR-005 §RBAC Warning).
Capability resolution: Happens at the NestJS application layer via @RequiresCapability() decorator. Hasura permissions handle role + tenant scoping; NestJS handles fine-grained capability checks on Actions.
Column-level restrictions (deferred): Phase 1 uses table-level permissions. We can add column-level restrictions (e.g., hiding bank_details JSONB from DISPATCHER) when a concrete privacy requirement surfaces.
Row-level for Drivers: Driver permissions use relationship-based filtering (through leg_assignments → service_legs → etc.). This is the most complex Hasura permission configuration — test thoroughly with multi-driver, multi-departure scenarios.
Subscription Tier Gating: The Nhost custom claims webhook (the same mechanism that injects x-hasura-tenant-id and x-hasura-role per ADR-005) also queries tenant_subscriptions.plan_id and injects X-Hasura-Plan into session variables. Premium features require explicit gating rules (tier-to-feature mapping TBD by product). The gating mechanism and strategies (including the upsertPricingConfig Action workaround for column-level limitations) are defined by ADR-030 and L3-6.2.2 (Schema Matrix Enforcement).

Busflow Docs

RBAC Matrix ​

Design Principles ​

Notation ​

Backoffice Schema ​

Commerce Schema ​

Operations Schema ​

Communications Schema ​

Public & Passenger Access ​

anonymous (Hasura public role) ​

passenger [future] ​

Consumer ETA Tracking (token-secured, no auth) ​

Hasura Actions — Role Matrix ​

Driver Data Scoping ​

Platform Role: busflow_staff ​

Implementation Notes ​

RBAC Matrix

Design Principles

Notation

Backoffice Schema

Commerce Schema

Operations Schema

Communications Schema

Public & Passenger Access

`anonymous` (Hasura public role)

`passenger` `[future]`

Consumer ETA Tracking (token-secured, no auth)

Hasura Actions — Role Matrix

Driver Data Scoping

Platform Role: `busflow_staff`

Implementation Notes