Operations

This is the operator's guide for the Matters.AI Partners Portal (apps/partners) — every environment variable it reads, the npm scripts that run it, how the Neon schema is managed, how the seed and bootstrap scripts work, and the end-to-end production deployment to partners.matters.ai. It mirrors the operational runbook in the repo PENDING_TASKS.md (both the Production Deployment §§A–H block and the Multi-Account Login block) and the per-service reference in apps/partners/PENDING_TASKS.md.

The portal is a standalone Next.js app on port 4005 with its own Clerk app, its own air-gapped Neon Postgres project, and its own R2 bucket — fully separate from workspace/memo. Nothing here is shared with the other apps.

Related pages: Data model · Auth · RBAC · Salesforce · Runbook

Environment variables#

The canonical template is apps/partners/.env.example. Copy it to .env.local and fill in real values — never commit secrets. For local prod-like runs the repo also reads, in order, ~/.envs/.matters-ai/.env.partners.prod, then .env.local, then .env, then .env.prod (this load order is defined in drizzle.config.ts and each script — the first file to set a key wins).

Variables prefixed NEXT_PUBLIC_ are bundled into the browser; everything else is server-only and must never be referenced from a Client Component.

Clerk — authentication#

The Partners portal gets its own Clerk application, separate from workspace/memo.

Neon PostgreSQL — database#

A separate Neon project, air-gapped from workspace/memo.

Cloudflare R2 — partner assets#

Stores partner logos, MDF documents, and signed agreements. Browser uploads use presigned URLs.

Upstash Redis — rate limiting#

Backs rate limiting on the SF callout and auth routes.

Resend — outbound email#

Sends invitations, deal notifications, and access-request approval/rejection emails.

Sentry — observability#

Error tracking is wired in instrumentation.ts (Node + edge runtimes) plus sentry.server.config.ts / sentry.edge.config.ts; it activates only when a DSN is present.

Salesforce — JWT Bearer (deferred; CSV mode is the v1 default)#

v1 runs in CSV mode: when SF_CLIENT_ID is unset, partner lookup reads the seeded partner_accounts table instead of live SOQL. Provide all of these only when switching to live SF — the data layer flips over with zero code changes. See Salesforce.

App, cron, and host gate#

Super-admin and multi-account flags#

Either path grants Super Admin — Matters.AI Clerk org membership (MATTERS_CLERK_ORG_ID) or a verified email in SUPER_ADMIN_EMAILS. See Auth and RBAC.

Scripts#

All scripts run from apps/partners with env loaded from .env.local (or use the pnpm --filter @matters/partners <script> form from the repo root). Defined in apps/partners/package.json.

Schema management#

The schema lives in lib/db/schema.ts. The runtime client is lib/db/client.ts — a lazily-cached Neon serverless Pool driven by drizzle-orm/neon-serverless with casing: "snake_case". The Neon DB is manually managed: any un-applied schema change makes the dependent pages 500 behind the generic error boundary, so the schema must be pushed before the matching code goes live.

The canonical path: db:push#

cd apps/partners
pnpm db:push

This diffs lib/db/schema.ts against the live Neon database and applies the changes directly. It is the path used in this repo (the drizzle/ migration files are not a complete from-scratch history — prefer db:push).

History — was broken on Postgres 18, now FIXED. On Neon Postgres 18 with the old drizzle-kit 0.28.1, db:push emitted spurious DROP CONSTRAINT … not_null statements and failed with Postgres error 42P16 (applying nothing). It is now fixed and verified by upgrading to drizzle-orm@0.45.2 + drizzle-kit@0.31.10 (the versions pinned in package.json); the diff against PG18 is now clean.

Two harmless quirks remain once it works:

1. It needs a real TTY. drizzle.config.ts sets strict: true, so db:push shows a confirm prompt before mutating. Run it in an interactive terminal, not a piped or CI shell — a non-interactive run can't answer the prompt.
2. It always lists ~7 cosmetic array no-ops. Every run reports about seven ALTER COLUMN … SET DEFAULT '{}' re-assertions for array columns. These are idempotent no-ops — just confirm them.

Fallback: direct additive DDL (non-interactive contexts)#

When you can't get a TTY (CI, a piped shell), apply idempotent additive DDL directly against the Neon SQL console instead of db:push. For example, the multi-account composite-unique change on partner_sessions:

-- drop the old single-column unique (substitute the real constraint name from \d partner_sessions)
ALTER TABLE partner_sessions
  DROP CONSTRAINT IF EXISTS partner_sessions_clerk_user_id_unique;

-- add the composite unique index
CREATE UNIQUE INDEX IF NOT EXISTS partner_sessions_user_org_unique
  ON partner_sessions (clerk_user_id, clerk_org_id);

Verify with pnpm db:studio — confirm the new index exists and the old one is gone. See Data model for the full table list.

Seeding#

Both seed scripts are idempotent upserts — re-running them updates rows in place, never duplicates. Each loads env from the same four-file order as drizzle.config.ts and exits 1 if PARTNERS_NEON_DATABASE_URL is missing. They use the one-shot drizzle-orm/neon-http driver (not the websocket Pool).

seed:csv — partner accounts (CSV mode)#

scripts/seed-from-csv.ts reads .sf_partners_data.csv from the current working directory (a Salesforce export), parses it with a small quote-aware CSV parser, derives a normalised websiteDomain from each Website (strips www., lowercases), and upserts into partner_accounts keyed on sfAccountId (onConflictDoUpdate). New rows are created with portalStatus: "active". This table is what CSV mode authorizes partners against when SF_CLIENT_ID is unset.

cd apps/partners
pnpm seed:csv   # reads ./.sf_partners_data.csv

Expected columns include Account Name, Account ID, Website, Partner Account Name, Account Type / Partner Account: Type, Partner Account: Industry, Partner Account: Billing Country / City, and Partner Account Owner. Rows without an account name are skipped.

seed:tiers — the three PRD tiers#

scripts/seed-tiers.ts upserts exactly three tiers — registered, silver, gold — into partner_tiers, keyed on the unique slug. Per the Partner Portal PRD v1.1 there is no Platinum tier, and margin/MDF are configured per-deal, not per-tier — so arrRange, mdfQuarterlyLimitUsd, and dealProtection are intentionally left null. Each tier carries its displayName, description, sortOrder, and benefits / requirements arrays.

cd apps/partners
pnpm seed:tiers

Super-admin bootstrap#

scripts/bootstrap-super-admin.ts (run via pnpm bootstrap:super-admin) provisions the internal Matters.AI Super Admin in the Partners Clerk app. It calls the Clerk Backend API directly with CLERK_SECRET_KEY and is fully idempotent.

pnpm --filter @matters/partners bootstrap:super-admin
# or target a specific person / org:
pnpm --filter @matters/partners bootstrap:super-admin -- --email eshank@matters.ai --org "Matters.AI"

What it does:

1. Finds or creates a Clerk organization named Matters.AI (default; override with --org).
2. Finds the target user by email (default: first entry of SUPER_ADMIN_EMAILS, else eshank@matters.ai; override with --email). If the user exists it adds them — or promotes them — to org:admin (inspecting existing membership first so re-runs never error). If the user doesn't exist yet it sends an org:admin organization invitation; they accept via inbox, then sign in at /accept-invite.
3. Prints the org ID — copy it into MATTERS_CLERK_ORG_ID (Vercel + .env.local) and keep SUPER_ADMIN_EMAILS=eshank@matters.ai as the fail-safe.

No secrets are printed — only the resulting org ID and a status summary. Requirements: a valid CLERK_SECRET_KEY for the Partners app and Organizations enabled in that Clerk app. See Auth and RBAC for how the org/allowlist resolves into the 7-type account model.

Deployment#

Target: Vercel, production domain partners.matters.ai. The recommended go-live order is a CSV-mode launch (skip Salesforce): A Neon → B Clerk → C R2 → D Upstash → E Resend → F Sentry → G Vercel. The division of labour: a human creates each third-party account / secret / DNS record; the env wiring, schema push, seeds, and bootstrap are then mechanical.

A. Neon — production database#

console.neon.tech → New Project → copy the connection string → set PARTNERS_NEON_DATABASE_URL. Apply the schema with pnpm db:push (see Schema management), then run pnpm seed:tiers + pnpm seed:csv. Verify all tables exist in the Neon console.

B. Clerk — production app#

dashboard.clerk.com → Create application (Email sign-in only). Copy NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (pk_live_…) + CLERK_SECRET_KEY (sk_live_…). Add a Webhook → https://partners.matters.ai/api/webhooks/clerk, events organizationMembership.created + user.deleted → CLERK_WEBHOOK_SECRET. Set the Invitations redirect → https://partners.matters.ai/accept-invite. Then run pnpm bootstrap:super-admin and paste the printed MATTERS_CLERK_ORG_ID. (If running multi-account, also enable Multi-session handling under Configure → Sessions, on each instance.)

C. Cloudflare R2 — file storage#

Uploads/downloads fail without this. dash.cloudflare.com → R2 → bucket matters-partners. Add the CORS rule (browser uploads break without it):

[
  {
    "AllowedOrigins": [
      "https://partners-portal.matters.ai",
      "https://partners.matters.ai",
      "http://localhost:4005"
    ],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["Content-Type", "Content-Length"],
    "MaxAgeSeconds": 3600
  }
]

The production origin is partners-portal.matters.ai. If it is missing from AllowedOrigins, the presign route returns 200 but the browser's direct PUT to R2 is blocked by CORS, so every upload (MDF attachments, logos, content, agreements) fails. Keep both hostnames listed.

Create an R2 API token (Object Read & Write) → R2_ACCESS_KEY_ID + R2_SECRET_ACCESS_KEY; account ID → R2_ACCOUNT_ID; set a custom domain partners-assets.matters.ai → R2_PUBLIC_URL

• NEXT_PUBLIC_R2_PUBLIC_URL; R2_BUCKET_PARTNERS=matters-partners.

D. Upstash Redis — rate limiting#

console.upstash.com → Create Database (Regional, lower latency for rate limiting) → copy REST URL + token → UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN.

E. Resend — outbound email#

resend.com → Domains → Add Domain (matters.ai / mail.matters.ai) → add the SPF / DKIM / DMARC DNS records Resend provides. Create a sending-scoped API key → RESEND_API_KEY; set RESEND_FROM_EMAIL=partners@matters.ai. Required for approval/rejection emails to send.

F. Sentry — error tracking#

sentry.io → Create Project (Next.js) → DSN → SENTRY_DSN_PARTNERS (optional source-map upload during build: SENTRY_AUTH_TOKEN). Code is already instrumented via instrumentation.ts.

G. Vercel — deploy#

cd apps/partners && vercel link (needs your Vercel login). Root Directory: apps/partners; framework auto-detects as Next.js. Push every env var (vercel env add …). Set Production Domain partners.matters.ai (+ DNS), NEXT_PUBLIC_APP_URL=https://partners.matters.ai, and CRON_SECRET (openssl rand -hex 32, guards /api/cron/*). The host allowlist is hardcoded in middleware.ts (partners.matters.ai + loopback) — there is no ALLOWED_HOSTS env var to set. After the first deploy, repoint the Clerk webhook + invitation redirect at the live domain.

H. Salesforce — DEFERRED (v1 runs on CSV)#

Not needed for launch. While SF_CLIENT_ID is unset, the portal authorizes partners via the seeded partner_accounts. For live SF later — RSA keypair + Connected App + integration user + custom fields — see Salesforce and apps/partners/PENDING_TASKS.md §3. The data layer switches over with zero code changes.

Multi-account login (optional, ships OFF)#

Multi-account login (sign into up to 3 accounts in one browser) is built but gated behind NEXT_PUBLIC_MULTI_ACCOUNT_ENABLED, which defaults off. To enable it: (1) set NEXT_PUBLIC_MULTI_ACCOUNT_ENABLED=true on each environment, and (2) toggle Multi-session handling ON in the Clerk Dashboard (Configure → Sessions) — per instance (dev for local/e2e, prod for the live site). With the flag off, exactly one partner_sessions row exists per user and the account-type RBAC behaves as single-account. Before flipping it on in prod, apply the composite (clerk_user_id, clerk_org_id) unique on partner_sessions (see the direct-DDL fallback). See RBAC for the account-type org-scoping model.

Day-to-day operation#

Once live, the 7-type account-type RBAC (pending · rejected · prospect · partner · internal_team_member · admin · super_admin) is run entirely from the UI — no scripts:

• /admin/accounts — assign account types (Super Admin only). External emails can never be set to an internal type.
• /admin/access-requests — approve (→ partner, provisions the Clerk org + invite + approval email) or reject (→ rejected, sends the rejection email) pending external requests. Domains that match a seeded partner_accounts row auto-approve to partner on first login.
• /admin/activity — the append-only audit log (filter by org / actor / action / date), visible to all internal tiers.

Guard rails are automatic: the last super_admin can't be demoted, every approval/rejection is an all-or-nothing transaction, and account type mirrors to Clerk and self-heals on drift. Full detail in RBAC and the operational Runbook.