Partners service¶
Partners are Tomoda's multi-tenant scoping anchor: merchants, advertisers, organizations, or any other non-user entity that needs its own data and its own group of operators. Access to a partner is granted via PartnerMembership rows, not via the global User.Role field — so a standard user can also be a partner Tomoda account, and an account_type = partner account doesn't automatically have access to any specific partner until a membership is created.
| Source file | Purpose |
|---|---|
backend/internal/models/partner.go |
Partner, PartnerMembership, PartnerStatus, PartnerMembershipRole, PartnerMemberView |
backend/internal/services/partner/store.go |
CRUD + membership + "≥1 owner" invariant, partner.ErrLastOwner |
backend/internal/services/partner/service.go |
Slug validation, creator-becomes-owner rule |
backend/internal/services/partner/handler.go |
REST endpoints |
backend/internal/services/partner/routes.go |
partner.Routes: the workspace route table, each entry naming its capability |
backend/internal/access/authorizer.go |
Membership check for partner capabilities |
Data model¶
Partner (id, slug, name, status, timestamps)
└─ PartnerMembership (partner_id, user_id, role)
role ∈ {owner, admin, member}
UNIQUE (partner_id, user_id)
slugis unique, URL-safe (lowercase alphanumerics + hyphens, 2-64 chars), but routes use{partner_id}(UUID) rather than slug: the slug is for display.statusisactiveorsuspended(PartnerStatus), defaulting toactivevia the model'sBeforeCreatehook. It records operational state; the access gates key off membership + role, not status.
See architecture/data-model.md → Partners for the cross-domain view.
Membership roles¶
Distinct from the global UserRole enum — these mean different things.
| Role | Allowed actions |
|---|---|
owner |
Billing, delete partner, manage other owners/admins/members. ≥1 required. |
admin |
Manage members and all partner resources. |
member |
Manage resources; cannot manage members or billing. |
The member role was called staff. Rows keep storing staff and the code reads it as member, so the previous release still reads every membership; a later release rewrites the rows and writes member.
Access gates¶
Workspace routes are the table partner.Routes; each entry names a partner capability and is mounted with Authorizer.Require, which reads {partner_id} from the route and looks up the caller's membership (and the workspace status) in one query. See Access control.
| Capability | Allowed roles | Use for |
|---|---|---|
partner.workspace.read |
owner, admin, member |
Read-only partner views |
partner.workspace.action.manage |
owner, admin |
Write, member management |
partner.billing.action.manage |
owner |
Delete partner, billing, owner management |
One DB read per request. A membership rejection or a suspended workspace returns 403. Cache (e.g. Redis partner_membership:<p>:<u> with invalidation on add/remove/role-change) is a follow-up if this becomes a hot path.
On success the gate places partner_id and partner_role onto the request context (api.WithPartner), read downstream via api.PartnerID(r) and api.PartnerRole(r).
Routes¶
All routes require JWT auth via the standard JWTAuth middleware.
Unscoped¶
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/v1/partners |
any authenticated | Create a partner; caller becomes owner |
| GET | /api/v1/me/partners |
any authenticated | List partners I belong to |
Scoped — /api/v1/partner/{partner_id}/...¶
Every route names its capability in partner.Routes.
| Method | Path | Required role | Purpose |
|---|---|---|---|
| GET | /api/v1/partner/{partner_id} |
any member | Get the partner |
| GET | /api/v1/partner/{partner_id}/members |
any member | List members |
| PATCH | /api/v1/partner/{partner_id} |
admin | Update name, status |
| POST | /api/v1/partner/{partner_id}/members |
admin | Add a member |
| PATCH | /api/v1/partner/{partner_id}/members/{user_id} |
admin | Change a member's role |
| DELETE | /api/v1/partner/{partner_id}/members/{user_id} |
admin | Remove a member |
| DELETE | /api/v1/partner/{partner_id} |
owner | Delete the partner |
Invariants¶
The store (backend/internal/services/partner/store.go) enforces these at the storage layer inside transactions so concurrent writes can't violate them:
- ≥1 owner per partner.
RemoveMemberandUpdateMemberRolereturnpartner.ErrLastOwnerwhen the change would leave the partner without an owner. The handler translates this to409 Conflict. - Creator becomes the first owner.
Service.Createinserts the partner, then a membership withrole=owner, and rolls back the partner row (best-effortDelete) if the membership insert fails. - One membership per (partner, user). Enforced by the composite unique index on
(partner_id, user_id).
Frontend wiring¶
| File | Role |
|---|---|
frontend/services/partnerService.ts |
REST client matching the route table above |
frontend/hooks/usePartners.ts |
TanStack Query hook (partnersQueryKey) fetching /me/partners; exposes partners, membershipFor, roleFor, refresh |
frontend/hooks/useAccess.ts |
inPartner, canAdminPartner, canOwnPartner helpers (alongside the Tomoda-team flags) |
frontend/app/partner/ |
Partner ops shell under /partner (dashboard, members, events, hub); placeholder screens today |
There is no "current partner" state in the frontend; partner context on the API side is always URL-derived.