SoConnective — Documentation

Date: 2026-06-10
Status: Accepted (implements ADR 0002 §2, §4.3)
Authors: Claude Code · Pamela

Context

Phase 1 needs a CRM to manage prospects and clients "like Notion": companies, contacts, and (next) leads and a pipeline, with per-tenant isolation and a usable admin UI.

Decision

Build the CRM as Payload collections using @payloadcms/plugin-multi-tenant:

A tenants collection is the tenant registry for Payload-managed data.
CRM collections (companies, contacts, → leads, deals) get a tenant field and are scoped per tenant by the plugin; users see only their tenant's records.
Payload provides the admin UI, auth, access control, REST + GraphQL APIs for free.

This follows ADR 0002 §4.3: Payload is the admin/CRUD/auth backbone; the heavy analytical/financial data (campaigns, insights, billing ledger, domain events) stays in our own public schema RLS tables (packages/db), not in Payload.

Boundary to watch (two tenant concepts)

There are now two tenant notions: Payload's tenants (payload schema) and the domain's organizations (public schema, RLS). They must be kept in sync (one is the registry, the other the RLS partition). Reconciling them into a single identity is tracked for the identity-unification step (ADR 0002 §7). For now, Payload tenants drives the CRM.

Consequences

Immediate, Notion-like admin for the CRM with tenant isolation; no hand-built UI.
REST + GraphQL endpoints per collection out of the box (API reference: OpenAPI/Scalar, next step).
The Payload↔domain tenant mapping is the main thing to get right as we grow.