Multi-tenancy
Arkyc is multi-tenant from the ground up: each tenant is an organization. Every scoped table carries an organization_id (and a project_id where relevant), and every query, storage path, and route is organization-scoped. Retrofitting isolation is explicitly avoided.
The hierarchy
Organization ──< Project ──< VerificationSession ──< captures / checks / reviews
│ │
│ └──< ProjectMember, ApiKey, WebhookEndpoint
└──< OrganizationMember, Role, OrganizationInvitation- Organization: the tenant. Has a unique
slug(used for addressing in the dashboard),name,logo_url, and a free-formsettingsJSON. - Project: an application/environment within an organization. Carries
environment,settings,branding, verificationthresholds, andstatus. Slug is unique within the organization. - VerificationSession: scoped to both
organization_idandproject_id.
Verification
Every organization is treated as a business. It can build and test in development and staging straight away, but runs production projects only once verified.
Members
Membership is two-layered:
- OrganizationMember: the primary membership. One per
(organization, user), with arole_idand astatusofactive/invited/suspended. Only active members can access an organization. - ProjectMember: optional, narrower scoping. One per
(project, user), with its ownrole_id. A user can belong to an organization without any project membership.
New members are added via invitations: an email + role + hashed token with an expiry. Accepting the invite creates the active OrganizationMember. A signed-in user with a verified email can also accept invitations addressed to them from the dashboard's Invitations page, without the link.
Active-organization resolution
Dashboard routes are shaped /v1/dashboard/organizations/:organizationId/.... The resolveOrganization middleware (after auth):
- Loads the organization by id.
- Confirms the authenticated user is an active
OrganizationMember(rejectinginvited/suspendedwith403). - Attaches
req.organizationandreq.organizationMemberfor downstream handlers and thecan(...)permission guard.
The dashboard addresses organizations by slug in the URL and resolves the slug to the organization id client-side.
Effective permissions per request
GET /v1/dashboard/organizations/:organizationId/me returns the caller's role_permissions, direct_permissions, and the deduplicated effective_permissions for the active organization. The dashboard uses this to render permission-aware navigation and actions. See RBAC & permissions for how the effective set is composed.
Isolation guarantees
- Foreign keys + indexes on
organization_id/project_idon every scoped table. - Cascade deletes from organization → projects → sessions → captures/checks.
- Storage keys are namespaced
organizations/{organizationId}/projects/{projectId}/sessions/{sessionId}/…. - The public/client APIs resolve organization + project from the API key / client token, so a key can only ever touch its own project's data.
