Roles & Permissions

Onoots distinguishes between human actors (brokerage members and buyers), the AI swarm (autonomous non-human actors), and the technical roles that govern data access. Every sensitive action — closing a commission, approving compliance, switching an AI agent on — is gated by a specific authority.

Actor hierarchy


                          ┌─────────────────────────────┐
                          │   ACCOUNT / BUSINESS (owner) │  ← creates the brokerage
                          │   creates the brokerage +    │     and the first broker
                          │   first broker               │
                          └──────────────┬──────────────┘
                                         │
                    ╔════════════════════▼════════════════════╗
                    ║              BROKERAGE                    ║
                    ╠══════════════════════════════════════════╣
                    ║   BROKER   (principal · top authority)    ║
                    ║      │  approves deals/equity/compliance  ║
                    ║      │  AI kill-switch · settings · $     ║
                    ║      ▼                                    ║
                    ║   TEAM LEAD  (agent + supervises/recruits)║
                    ║      │  earns sponsor_share on recruits   ║
                    ║      ▼                                    ║
                    ║   AGENT  (lists · qualifies · closes)     ║
                    ╚═══════════════════╤══════════════════════╝
                                        │  serves
                                        ▼
        ┌──────────────────────────────────────────────────────┐
        │   DEMAND (buyers)                                     │
        │   • Lead   → anonymous prospect (no account)         │
        │   • Client → authenticated buyer (in chat)           │
        └──────────────────────────────────────────────────────┘

   ┌────────────────────────── AI SWARM ──────────────────────────┐
   │  Marketer · Qualifier · Scheduler · Nurture · Concierge · …   │
   │      everything passes →  🛡️ COMPLIANCE GUARDIAN  (hard gate) │
   │                  allow / prepare / escalate / block           │
   └───────────────────────────────────────────────────────────────┘

Brokerage human roles

Every brokerage member holds exactly one of three roles:

Role	Description
Broker	Brokerage principal/owner. Top authority: finalizes commissions, approves compliance and equity, manages billing, settings, and the AI swarm kill-switch. Sees the whole brokerage.
Team Lead	An agent who also supervises other agents. Inherits agent permissions and can sponsor recruits, earning `sponsor_share` on their deals.
Agent	Individual sales agent. Creates listings, qualifies leads, manages their own deals, and drives them to close.

The founder who creates the brokerage during onboarding is materialized as the first Broker — it is not a separate role.

The demand side: buyers

Actor	How they’re represented
Dreamer	The lightest actor of all: an anonymous visitor who couldn’t find their property and leaves one message describing their dream home + an email, no account. Dreams go to a global platform registry. When a new listing matches, the Nurture agent emails them.
Lead	Prospect with no account. Arrives via a listing form, a referral link, the AI chat, or manual entry. Moves through states: auto-assigned → pool → broker-assigned → closed.
Client	Authenticated buyer who joins a lead or deal chat. Can message their agent and keep exploring properties without being part of the brokerage.

Onoots Dreams turns latent demand into opportunity: the dreamer describes what they want, and when supply appears the swarm matches it (AI scoring, gated by the Compliance Guardian) and emails them — with an unsubscribe link. The brokerage that published the listing pays for that reach (it’s their property).

The AI swarm (non-human actors)

AI agents act autonomously on business events (a published listing, a new lead…), but no action runs without passing the Compliance Guardian.

AI agent	Function
Marketer	Generates listing content and posts to social media.
Qualifier	Buyer concierge in the chat: replies and qualifies intent.
Compliance Guardian	Hard gate. Evaluates every swarm action and decides: `allow`, `prepare`, `escalate` (request human approval), or `block`.
Scheduler · Nurture · Concierge · Onboarder · Orchestrator	Showing scheduling, follow-up, post-offer, pre-listing, and coordination (evolving per roadmap).

The Broker controls the swarm: toggles each agent on/off (kill-switch) and sets the Autonomy Policy (how much the AI may do without human intervention).

Permissions matrix

Legend: ✅ allowed · 🔒 own only · 👀 read-only · ⛔ denied

Action	Visitor	Lead/Client	Agent	Team Lead	Broker
View public listings	✅	✅	✅	✅	✅
Leave a dream (Dreams)	✅	✅	✅	✅	✅
Submit lead / request showing	✅	✅	✅	✅	✅
Chat with the Qualifier	✅	✅	—	—	—
Create/view own listings	⛔	⛔	🔒	🔒	✅
View own assigned leads	⛔	⛔	🔒	🔒	✅
View the lead pool	⛔	⛔	✅	✅	✅
Move a deal’s stage	⛔	⛔	🔒	🔒	✅
Finalize commission (money close)	⛔	⛔	⛔	⛔	✅
Compliance queue / PDF	⛔	⛔	⛔	⛔	✅
Finance / exports / audit-trail	⛔	⛔	⛔	⚠️ exports	✅
Checklist templates (CRUD)	⛔	⛔	👀	👀	✅
Recruit / view recruits	⛔	⛔	🔒	✅	✅
AI kill-switch / Autonomy Policy	⛔	⛔	⛔	⛔	✅
Billing & credits	⛔	⛔	⛔	⛔	✅

Relationship roles

Beyond the primary role, actors connect to one another:

Recruitment: a sponsor (Team Lead or Broker) recruits an agent and earns sponsor_share on their deals.
Referrals: agent→agent, recruitment, or client_link (a public link for a client to refer someone they know).
Conversations: each participant has an owner, participant, or observer role (the Broker typically joins as a read-only observer).
Signatures: each document defines signers (buyer, seller, agent, and custom roles per checklist).

Technical roles (data access)

Under the hood, Onoots enforces row-level security (RLS) over three roles:

Technical role	Who it is	Access
anon	Public visitor	View listings, submit leads, request showings (rate-limited).
authenticated	Logged-in user (broker/agent/client)	Brokerage-scoped access via `is_agent_of` / `is_broker_of`.
service_role	System (cron · worker · swarm)	Internal operations; never exposed to the client.

Money and compliance actions have a double barrier: validation at the API layer and in the database (e.g. finalizing a commission requires being a Broker of that brokerage in both the route and the SQL function).