Roles & dashboards

IssuesId is built around the idea that everyone on a job has a different job. A trade doesn't need to see all defects on a project — only the ones they own. A client doesn't need to assign work — only see how it's going. So instead of one "users" model with permissions tacked on, every user has a role, and the role drives both what they see and what they can do.

There are seven roles. Each has a dashboard tailored to their workflow.

Role	Scope	Can close defects?
Company Admin	Whole organisation	From any state
Manager	Assigned projects	From `open` or `ready_to_inspect`
Building Manager	Building / section	From `open` or `ready_to_inspect`
User	Project, on-the-ground	From `ready_to_inspect` only
Trade	Assigned work only	No
Tenant	Single unit	No
Client	Read-only	No

(Role labels above match what's shown in the app's user list.)

The seven roles

Company Admin

The owner-operator role. Sees everything across every project in the organisation — all defects, all work orders, all settings. Configures integrations, manages users, drives the build from the top. The only role that can drive a defect into closed from any non-standard state.

Manager

Scoped to assigned projects. Assigns defects to trades, approves work orders, signs off inspections, and drives the day-to-day. Can close defects from open (declined / not-a-defect path) and from ready_to_inspect (the standard close-out path).

Building Manager

Scoped to a building or a section of a project. Inspection-focused — runs QA checklists, signs off areas as complete. Holds the same close-out authority as Manager (open and ready_to_inspect) but a smaller transition matrix elsewhere.

User

The on-the-ground capture role. Captures defects, raises work orders, signs inspection items. Can drive defects across most intermediate transitions, including ready_to_inspect → closed when verifying a fix in the field. Can't close defects from any other state — those paths are reserved for managers.

Trade

The sub-contractor role. Only sees what's assigned to them. Updates assignment status (e.g. marks work complete) but never transitions defect state directly — that stays with the assigning manager. This is what stops trades from closing their own work.

Tenant

Scoped to a single unit. Sees only defects in their own unit. Can comment to add context, can't transition state. Used for end-user portals in residential and commercial fit-out projects.

Client

Read-only view of defects, work orders, and any acknowledgement-required documents distributed to them. No state changes. The role you'd give to a client representative who wants visibility without operational access.

Role-gated transitions

Defect state changes follow a strict matrix — not a permission flag, but a hard-coded set of allowed transitions per role. This is what keeps the audit trail honest:

→Trades, tenants, and clients have zero defect transitions. Trades update their assignment status (e.g. "I've completed my work"), but never change the defect's own state. That separation is what stops a contractor from closing their own work.
→Users can drive defects through the field-facing transitions, including verifying a fix at ready_to_inspect → closed. They can't close from any other state.
→Managers and Building Managers add the open-state close path (decline / not-a-defect) on top of what Users can do.
→Company Admins are the only role that can close a defect from any non-standard state — used for cleanup of stuck or escalated records.

If a role tries a transition they're not allowed to make, the API refuses. There's no override, no "just this once." If the workflow needs to bend, it bends in the matrix, not at the request.

Multi-org membership

A single user account can belong to multiple organisations and switch between them. Each membership carries its own role — you might be a project manager in one org and a client in another. The dashboard switches with the org.

Why this matters for handover

Because every action is performed by a known role with a known scope, the audit trail isn't just "user X did Y" — it's "user X, acting as project manager on project P, did Y at timestamp T." That's the level of evidence that holds up in disputes, claims, and PC sign-off.