Concepts
The platform's vocabulary. Read this once and the rest of the docs will make sense.
The hierarchy
Tenant
└── Workspace
└── Project
└── (resources: files, conversations, jobs, ...)
- Tenant — your organization. The boundary for billing, SSO, and tenant-wide policy.
- Workspace — a team's home. The boundary for membership and most resources.
- Project — a unit of work inside a workspace. The boundary you most commonly share.
- Resource — a thing (file, message, job, form). Lives inside a project.
→ Workspaces, projects, tenants
Identity
Every action on the platform is performed by an actor. An actor can be:
| Type | Example |
|---|---|
user | A human signed in via password/SSO |
app | A registered application acting via OAuth |
service | A platform service calling internally |
super_admin | Operator with cross-tenant access |
The API gateway authenticates the request and injects x-actor-id / x-actor-type headers downstream. Services never validate tokens themselves.
Federation & multi-tenancy
The API is a federated GraphQL graph composed from 40+ services. Clients see one schema; the gateway routes fields to the owning service. Multi-tenancy is enforced at the edge — every request carries tenant context, and services receive it via headers.
Eventing
Cross-service communication is event-driven via the event bus. Services publish events; consumers subscribe with consumer groups for at-least-once delivery.
RBAC
Every public field on the GraphQL graph carries an @rbac directive. The gateway enforces it. Subgraphs never re-implement auth.
→ Deep dive: RBAC overview