User Roles And Permissions

A USER ROLE is a category of user with a specific set of permissions. A PERMISSION is a yes/no answer to "can this user do this thing?"

The standard roles, in order of power:

SUPER ADMIN / OWNER. Can do anything. Usually one or two people total. Can create other admins, change billing, delete the entire app. You do not give this role out casually.

ADMIN. Can manage users, see all data, change settings, but can't delete the entire app or change billing. The "managers of managers" tier.

MANAGER. Can see all data within their scope (their team, their location, their department), can edit and delete things in their scope, but can't change app-wide settings.

EDITOR / STAFF. Can create and edit content within their assigned area, but can't delete other people's work or change settings.

USER / CUSTOMER / VIEWER. Can see their own data and do their assigned tasks. Can't see other people's data or do anything administrative.

GUEST / PUBLIC. Can see public pages (the marketing site, the login form). Can't see anything that requires authentication.

For each role, write down:

1. What pages they can see.
2. What actions they can perform on each page.
3. What data they can read.
4. What data they can create, update, or delete.

For a small services business app, this might be:

ROLE: Owner

• Pages: Everything.
• Actions: All.
• Data: All.

ROLE: Office Staff

• Pages: Customers, Jobs, Calendar, Invoices.
• Actions: Create, edit, delete on all of the above.
• Data: All operational data. NOT financial reports or user management.

ROLE: Field Tech

• Pages: Today's Calendar, Job Details (assigned to them), Time Clock.
• Actions: View their own jobs. Mark jobs complete. Add notes and photos.
• Data: Only their own jobs. Cannot see other techs' schedules. Cannot see customer financial data.

ROLE: Customer (login enabled)

• Pages: Their dashboard, their jobs, their invoices, their payment history.
• Actions: View their data. Pay an invoice. Request a follow-up visit.
• Data: Only their own.

This document goes in roles.md in your repo. The agent reads it. The agent enforces it in code.

Common mistakes:

DON'T conflate "logged in" with "permitted to see this." Logged in means the system knows who you are. Permitted means the system has checked your role and decided you can see this specific thing. Both checks happen on every request.

DON'T put permission logic only in the frontend. The frontend can be bypassed (anyone can call the API directly). Permission checks happen on the backend, on every endpoint.

DON'T let agents add permission logic by inference. Specify it. If you don't write down "field techs can't see other techs' jobs," the agent might or might not implement it, and you might or might not notice until a tech sees something they shouldn't.