Functional contract
Staff access
A User is an independent login. Access to an Organization is a Staff record. What the person may do is a role assignment. Location grants are location-scoped assignments.
Membership
| Fact | Rule |
|---|---|
| Organization membership | A Staff record links a User to exactly one Organization. A User may have 0..N Staff records |
| Invite | Organization administrators invite by name and email. New emails create a User; existing emails reuse the login. Staff stays pending until the address is validated |
| Pending membership | accepted_at blank. No org access. User#primary_staff ignores pending records. Users & Roles shows days since last send and how many times the invite was issued |
| Resend invitation | Organization administrators resend a pending invite (PATCH /app/staffs/:id/resend). Rotates the token and increments the send count. Delivery is not built |
| Withdraw invitation | Organization administrators withdraw a pending invite. Destroys the Staff. The User login is unchanged |
| Disabled membership | disabled_at set. Same access denial as pending. The User login stays usable. Last enabled Organization administrator cannot be disabled |
| Settings | Staff#can_view_settings? (Organization administrator, Organization manager, Location administrator). Users & Roles tab only if can_assign_roles? |
| Location grants | Location-scoped role assignments. Organization-scoped assignments imply every Location |
| Current Location | Workspace scoped to one granted Location (or Organization overview). Sidebar switcher when the Staff has more than one Location; PATCH /app/workspace stores the choice |
| SuperUser | Not Organization staff. May impersonate a staff User from /admin/users and work in /app with that User’s Staff, workspace, and RBAC. SuperUser session stays. Stop at DELETE /admin/impersonation or /app sign-out. No UserSession, no login-stat update. API impersonation is not built |
| Customer | Later. A User may associate with one or more Customers without a Staff record |
Organization-scoped roles may use every Location. Catalog definition is SuperUser-only. See RBAC.
Roles
| Role | Scope | May |
|---|---|---|
| Organization administrator | Whole Organization | Assign any role, master catalog, all Locations, consolidated reports |
| Organization manager | Whole Organization | Org-wide read and consolidated reports. Cannot assign roles |
| Location administrator | Assigned Locations | Site ops and assigning location-scoped roles there. Cannot assign org-scoped roles |
| Receptionist | Assigned Locations | Scheduling, visits/check-in, patient admission, checkout |
| Veterinarian | Assigned Locations | Medical records (SOAP), visits, appointments as provider (read) |
A person can be Organization administrator and also a veterinarian at granted Locations. Location administrators cannot invite, resend, withdraw, or disable staff.
Invites
Organization administrators invite from Users & Roles (Staff.invite! / POST /app/staffs): first name, last name, email. The membership is listed as Pending, with days since the last send and how many times the invite was issued. Roles may be assigned before validation. A pending invite can be resent (PATCH /app/staffs/:id/resend) or withdrawn (DELETE /app/staffs/:id); withdraw deletes the membership only. Until Staff#accept!, that membership grants no access. Founder provision sets accepted_at. Invite email delivery and the accept-by-token page are not built.
Disable staff
Organization administrators disable an accepted membership (PATCH /app/staffs/:id/disable, disabled_at). Disabled Staff cannot act, are not bookable, and are omitted from User#primary_staff. Enable restores the same membership. The User record is never changed. The last enabled Organization administrator cannot be disabled.
Location switcher
- Lists Organization plus Locations the User is granted (
Staff#granted_locations). - Changing current Location keeps the same session and the same patient database.
- Hide the switcher when the User has exactly one Location grant (Organization scope still available when they have org-wide roles).
PATCH /app/workspacestores the choice in the session.
Reports and data visibility
| Viewer | Sees |
|---|---|
| Organization administrator / manager | Organization totals, each Legal Entity, each Location |
| Location roles | Only granted Locations |
| SuperUser | All tenants, for support |
Catalog rights
- Only Organization administrators edit the master catalog and lock items.
- Location administrators override unlocked attributes at granted Locations.
Details: Catalog and pricing.
Acceptance
- A veterinarian granted only A cannot open B.
- An Organization administrator can open every Location.
- A Location administrator at A cannot assign Organization administrator or operate B.
- SuperUsers authenticate only at
/admin/login. They may impersonate a staff User from/admin/usersand see/appas that person. Stop impersonating returns them to/admin/users. - An Organization administrator can invite a user; pending Staff cannot operate until accepted.
- Users & Roles shows days since last send and send count; the administrator can resend or withdraw the invite without deleting the User.
- An Organization administrator can disable a Staff membership without affecting the User login. The last enabled Organization administrator cannot be disabled.
- A Location administrator cannot invite, resend, withdraw, or disable staff.