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.matters.ai", "http://localhost:4005"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["Content-Type", "Content-Length"],
    "MaxAgeSeconds": 3600
  }
]

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.