Roles & permissions

How roles work in your community: the two-layer model (admin capabilities + community participation), the Resident built-in, and how to onboard staff who shouldn't appear in resident surfaces.

The two-layer model

Permissions in this platform are stored on roles, not on accounts directly. A role bundles capabilities and a community assigns roles to specific people. Two separate categories of capabilities live on each role:

Admin permissions: what someone can do on the management side of the portal. Ten modules: members, dues, financials, architectural reviews, violations, community issues, announcements, chat moderation, documents, and site settings. Each module has three cumulative levels: view, edit, and admin. A Treasurer role might grant finance/admin + dues/admin + users/view and nothing else.

Community participation: what someone can do on the resident side: post in chat, vote in polls, RSVP to events, upload event photos, host events, report community issues, submit architectural and resident-service requests, reserve amenities, request estoppel certificates, list in the marketplace, recommend vendors, register pets, browse the directory. Each capability is a simple on/off toggle. The Resident built-in role grants all fourteen by default.

Most people in a community get the Resident role (full participation, no admin grants). A volunteer treasurer gets Resident + Treasurer. A property-management employee who runs the system but doesn't live in the community gets Community Admin + nothing on the participation side. They can manage dues and approve residents, but they don't appear in the directory and can't RSVP to the block party.

The Resident role

Every approved community member gets the Resident role automatically. The role lives in the role library at /admin/roles alongside the other built-ins; communities can edit its participation grants in place to change baseline policy for everyone at once.

For example, if you want to disable resident-created polls community-wide (so only the board can start polls), open the Resident role and toggle off the vote_polls capability... wait, actually that disables voting, not creating. Creating polls is gated separately. The point is: editing the role propagates to every resident on next page load.

Admin scoped roles

Five built-in admin roles ship with sensible default grants and can be edited in place, cloned, or disabled per community:

Treasurer. Dues + Financials at admin level. View-only on members and documents.

Architectural Chair. Architectural reviews at admin level. View-only on members and documents; can also edit announcements.

Social Committee Chair. Announcements + calendar at admin level. View-only on members and documents.

Community Moderator. Chat moderation at admin level. View-only on announcements and members.

Maintenance Liaison. Community Issues at admin level. View-only on arch reviews, members, and documents.

Two system roles also exist (Sys Admin and Community Admin), but those are platform-level and only assigned via the legacy account_type flag, not the regular role assignment drawer.

Onboarding staff (non-residents)

Property-management employees, off-site board members, and other staff need admin access without resident participation. Two paths get them there:

From pending approval: on /admin/users, the sibling Approve as staff button next to the regular Approve. Both run the same approval, but the staff path skips the auto-assignment of the Resident role. The new staff member lands approved with no participation grants; assign their admin scoped role next.

For an existing user: open their profile → Roles tab. To remove resident participation, revoke the Resident role assignment (X button on the row). To grant it back later, use the prominent Grant resident access button at the top of the section.

A scoped admin's sidebar reflects their grant: the admin nav shows only the tools their role covers, and the "Admin Panel" hub link appears only when they have a tile to open there. Command-palette search is scoped the same way, and any admin page outside their grant redirects them out. So a Treasurer sees the money tools, an Architectural Chair works from the converged review page, and neither sees the other's surfaces.

On /admin/users, a member's built-in and custom roles now show as chips on the roster row and the member header (with a shield on admin-level roles). That's how you spot who holds a delegated role at a glance. someone can be a "Resident" by account type and still hold an Architectural Chair role with real admin access.

Custom roles

Clone any built-in role to create a custom variant. Common patterns:

"Limited Resident": clone Resident, untick all participation grants except chat_post. Assign to staff who need chat access for emergency outreach but shouldn't appear in other resident surfaces.

"Resident with Polls": clone Resident, enable a poll-creation capability (if your community wants to delegate poll authorship to all residents rather than only the board). Mark it is_default_for_new_residents=true and the approval flow assigns it instead of (or alongside) the base Resident role.

"Pool Committee": start from scratch. Maybe just announce/edit + chat/admin on a single channel. Assign to chairs who coordinate pool scheduling but don't need broader access.

Recognition badges are not roles

Badges such as Founding Member or 10 Years a Resident look like role pills, but they carry no permissions and never unlock anything. Set them up on Admin → Recognition Badges and give one from a member's Overview tab in User Management, with an optional note. Board Member stays a role.

Founding Member and the tenure badges are awarded automatically once a night, but they start switched off: nothing is given until you switch a badge on. Removing a badge from someone is permanent for the automatic ones, so the nightly run never gives it back. Residents can hide their badges from neighbors in their profile's privacy settings. Giving and removing badges shows up in the audit log.

Audit trail

Every change to a role or assignment writes to role_change_event. Editing the Resident role's participation grants logs separately from editing its admin grants (so the timeline distinguishes "policy change" from "matrix tweak"). Auto-assignments at approval time tag with source=approval_auto_assign so the audit reads as "Sarah was assigned Resident automatically at approval" rather than "Mark assigned Resident to Sarah."

Revocations soft-delete (the row sticks around with a revoked_at timestamp). Re- assigning after a revocation creates a new row, so the full history of "who was treasurer in 2024 vs 2025" survives indefinitely.