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	Assigned projects, defects 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 the work assigned to their own company. Updates assignment status but never transitions defect state directly — that stays with the assigning manager. This is what stops trades from closing their own work.

Three actions are available on an assignment:

→Mark as Complete — gated on evidence. At least one photo of the finished work must be attached first; until it is, the button stays disabled and says so. The rule is expressed as data rather than hard-coded, so what evidence is required for which transition can change without a rebuild.
→Dispute — "this isn't mine", "this isn't a defect", "I can't get access". Raises it with the project team and leaves a note in the thread rather than silently stalling.
→I'm on it — flags the work as in progress. It signals a start without claiming a finish, which is the state most trades were previously forced to fake by doing nothing.

A trade gets the same screens whether they log in or open a magic link from a notification email — same actions, same copy, no account required for the link.

Alongside their own work, a trade can read the project-level drawings and documents, see the work orders raised against them, and raise an RFI when a detail doesn't make sense on site. Correspondence is not theirs to see — see Correspondence.

Tenant

The resident or occupant role. Sees only the defects they raised themselves — not everything logged against their unit by the site team. Cost figures and contractor identity are stripped from what they see: a tenant learns that their issue is being dealt with, not who's being billed for it or how much.

Tenants can raise a defect themselves — that's the point of the role — and comment on one to add context. They can't move a defect's status by any route.

They also get the documents attached to their own unit and the project photo gallery. Not the project-level register: see Documents & drawings.

Client

Read-only visibility of defects on the projects they're assigned to. The role you'd give to a client representative or a consultant who wants to watch progress without operational access.

It is genuinely narrow. A client sees defects and can add a comment to one. No documents, no work orders, no search, no QR scanning. If a client needs a document, someone sends it to them; the register isn't theirs to browse.

The one report they can run is the Client Defect Summary, generated against a defect they can already see — and it's client-only, so nobody else raises it on their behalf by accident. See Reports.

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 from the account menu. 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.

The workspace you were last in is the one you land in next time, and it survives a full logout and a fresh login. This matters most for trades working across several builders: they don't get dropped into an arbitrary workspace each morning.

How a trade gets an account

A trade doesn't have to be invited, and shouldn't self-register a brand-new company — that's how you end up with three versions of the same plumber in the system.

Instead, their email is matched against the builder's contractor directory:

→Signing up with an email that appears on a builder's contractor or contact list provisions a correctly-scoped trade account inside that builder's organisation.
→Being assigned work does the same thing for a trade who already has an account — the link is made the moment a builder issues them a defect.
→Matching several builders links all of them, and they land in the one they most recently did work for.

An email that matches nothing doesn't create an orphan account in someone else's workspace; the person is offered their own workspace instead. Org admins are notified when a trade auto-enrols into theirs.

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.