Operations

This page is the single reference for memo's environment surface and how to keep the system running. Pair it with the in-repo apps/memo/DEPLOYMENT.md which has the click-by-click bootstrap.

Environment variables#

Memo expects ~42 environment variables in production (the full set is in apps/memo/.env.example). The core ones, categorized by what they unlock, are below; the realtime / collaboration and integrations groups are documented on Collaboration and Integrations.

Auth#

Database#

Storage#

Queues#

Recording#

Email#

Secrets#

Recording v3 toggles#

All three are independently toggleable. Set any to false to force off even when credentials are present. See /memo/replay for the full design.

Webhook cron (v3)#

Add to vercel.json crons (next to the existing two):

{ "path": "/api/cron/dispatch-webhooks", "schedule": "*/2 * * * *" }

Fires every 2 minutes. Picks up webhook_deliveries rows where delivered_at IS NULL AND next_attempt_at <= now(). Same dual-auth (Vercel CRON_SECRET or Upstash signature) as the other crons.

AI (v2)#

OAuth + MCP (v2)#

The OAuth server and /api/mcp need no additional env beyond what's already listed. The same Neon + Upstash + Clerk infra is reused. The PAT + OAuth tables were added in migrations drizzle/0001_*.sql and drizzle/0002_*.sql respectively — apply them on first deploy.

Observability#

Host / runtime#

Realtime / collaboration (v3.x)#

See Collaboration for the full realtime design.

Integrations (cloud import)#

Cloud-provider OAuth tokens are encrypted at rest. The encryption key is resolved from PROVIDER_TOKEN_ENCRYPTION_KEY, falling back to WEBHOOK_ENCRYPTION_KEY (src/lib/oauth/exchange.ts) — neither is in .env.example; provision one to enable token persistence. See Integrations.

Inbound email upload#

The full template lives in apps/memo/.env.example. It is also surfaced in turbo cache invalidation via turbo.json wildcards (NEON_*, R2_*, UPSTASH_*, QSTASH_*, LOGROCKET_*, CLARITY_*, MEMO_*, ALLOWED_HOSTS, etc).

R2 CORS for direct uploads#

The web client uploads files directly to R2 using presigned PUT URLs (the flow is presign → PUT → commit, with a unpack-zip chaser for ZIPs). This sidesteps Vercel's 6 MB request body cap, gives per-file progress events, and keeps server endpoints lightweight.

For the browser to be allowed to PUT cross-origin into R2, the memo bucket needs the CORS policy below. Apply it once per bucket — without it, every upload row fails with a Network error.

[
  {
    "AllowedOrigins": [
      "https://memo.matters.ai",
      "https://memo.matters.mreshank.com",
      "http://localhost:4004"
    ],
    "AllowedMethods": ["PUT", "GET", "HEAD"],
    "AllowedHeaders": [
      "Content-Type",
      "Content-Length",
      "Content-MD5",
      "x-amz-content-sha256",
      "x-amz-date",
      "x-amz-meta-*",
      "Authorization"
    ],
    "ExposeHeaders": ["ETag", "x-amz-version-id"],
    "MaxAgeSeconds": 3600
  }
]

Apply via the Cloudflare dashboard (R2 → memo → Settings → CORS Policy → paste) or via wrangler:

wrangler r2 bucket cors put memo --rules @apps/memo/scripts/r2-cors.json

Verify with:

curl -X OPTIONS \
  -H 'Origin: https://memo.matters.mreshank.com' \
  -H 'Access-Control-Request-Method: PUT' \
  https://<ACCOUNT_ID>.r2.cloudflarestorage.com/memo/staging/_probe -i

Expected 200 with Access-Control-Allow-Origin: https://memo.matters.mreshank.com.

The JSON is also committed at apps/memo/scripts/r2-cors.json so it can be applied non-interactively in setup scripts. The legacy multipart endpoint (POST /api/owner/projects/[id]/upload) is retained as a sub-4 MB fallback for CLI/MCP callers; CORS does not apply to it because the request is server-to-server.

Upload caps (server-side, enforced in the presign + unpack endpoints):

Crons#

Native Vercel crons are declared in apps/memo/vercel.json:

{
  "crons": [
    { "path": "/api/cron/rotate-jwt-key", "schedule": "17 3 * * *" },
    { "path": "/api/cron/expire-links", "schedule": "*/15 * * * *" },
    { "path": "/api/cron/dispatch-webhooks", "schedule": "*/2 * * * *" },
    { "path": "/api/cron/derive-cross-visit-signals", "schedule": "*/10 * * * *" }
  ]
}

Each cron handler accepts both:

• Vercel's automatic Authorization: Bearer ${CRON_SECRET} GET, or
• An Upstash-Signature-signed QStash POST.

This dual-auth lets us run the same endpoint from either system, which is useful for render-signed-pdf — that one is fired event-driven by /api/v/<slug>/sign via QStash, no Vercel cron entry.

rotate-jwt-key (daily, 03:17 UTC)#

Reads memo:jwt:key:current, demotes it to memo:jwt:key:previous with a 48-hour TTL, generates a new 48-byte base64 secret, and writes it to current. Visitor JWTs signed with the previous key continue to validate for 48 h after rotation.

expire-links (every 15 min)#

SELECT id FROM memo.links WHERE active = true AND expires_at < now() → for each, UPDATE active = false and write an audit_logs row with action='link.expire'. No-actor entries because the cron is the actor.

render-signed-pdf (event-triggered)#

Called from POST /api/v/<slug>/sign via QStash with { signatureId }. Reads the signature + agreement, calls renderSignedAgreementPdf (lazy @sparticuz/chromium-min + playwright-core), uploads to signatures/<signatureId>.pdf in R2, and back-fills signatures.signed_pdf_r2_key.

dispatch-webhooks (every 2 min)#

Picks up webhook_deliveries rows where delivered_at IS NULL AND next_attempt_at <= now(). For each, signs the body with HMAC-SHA256 (memo-signature: t=<unix>,v1=<hex>) and POSTs to the subscriber. On non-2xx response, increments attempts and sets next_attempt_at = now + 30s × 2^(attempts-1) (exponential backoff capped at 6 attempts).

derive-cross-visit-signals (every 10 min)#

Sweeps memo.visits rows in the trailing 72 hours, groups by visitor_persistent_id (for return signal) and by email domain (for share_detected signal), runs the pure classifiers from src/lib/analytics/derive-signals.ts, and upserts into memo.visit_signals with ON CONFLICT (visit_id, kind) DO UPDATE.

• return fires when ≥3 visits share the same visitor_persistent_id. Emitted on the most-recent of the qualifying visits so it surfaces "now" in the Activity feed.
• share_detected fires when ≥2 distinct emails from the same domain (lowercased) visit within the 72h window. Emitted on the most-recent of the colluding visits.

The cron writes one audit_logs row per run with action='visit_signals.derive' and meta={ windowHours, returnCount, shareCount } so you can confirm it's executing in production. See Observability → Cross-visit cron for the full algorithm.

Migrations#

Drizzle schema is the source of truth (apps/memo/src/lib/db/schema.ts).

The drizzle/ chain is a clean baseline — 0000_init.sql + meta/0000_snapshot.json — followed by 0001_slimy_morg.sql (the collaboration tables: project_members + project_invites). The prior chain's snapshots had drifted/become non-linear, so it was collapsed to 0000 and resumed linearly from there. The pre-Phase-1 → current incremental ALTERs (0006–0009) are archived in apps/memo/drizzle-legacy/ with a README. Apply paths:

• Existing DB → drizzle-kit push (recommended): diffs schema.ts against the live DB and applies exactly the gap, ignoring the migration files — so it works regardless of applied state. Review before confirming; a second run reports "No changes."
• Fresh DB → 0000_init.sql (or drizzle-kit migrate/push). Never apply 0000_init.sql to an existing DB — it CREATEs everything and will conflict; use push or the drizzle-legacy/ ALTERs in order instead.

Full detail: Runbook → Database migrations.

After any deploy that includes a schema change, sync the DB (push) BEFORE the new app code rolls. Otherwise routes that reference new columns/tables throw at runtime.

Vercel project shape#

• Build command: pnpm --filter @matters/memo build (Vercel's monorepo aware-build picks this up via turbo.json).
• Output directory: apps/memo/.vercel/output (produced by @astrojs/vercel).
• Node version: 22 (Vercel downgrades from local 24 automatically; warning is benign).
• Domains: memo.matters.ai as the canonical domain. The host gate rejects requests for any other Host header unless ALLOWED_HOSTS is widened.
• Functions: each /api/* route is a serverless function. Pages under /<slug>/* are also serverless.
• Crons: enabled via vercel.json. View status in the Vercel dashboard under Project → Settings → Cron Jobs.

Bootstrap order (first-time)#

1. Run the Drizzle migration against a fresh Neon database — this creates the memo schema with extensions.
2. Create the Mongo Atlas cluster and the memo database (the events collection is created lazily on first beacon).
3. Create the R2 bucket. Region: auto. No public access.
4. Create the Upstash Redis + QStash projects.
5. Create the memo-specific Clerk application. Set sign-in / sign-up URLs to /sign-in and /sign-up and the redirect URL to https://memo.matters.ai/.
6. Provision Resend with memo.matters.ai as a verified sending domain.
7. Provision LogRocket + Clarity projects.
8. Set all env vars (~42; see apps/memo/.env.example) in the Vercel project.
9. Deploy. Run the smoke test in DEPLOYMENT.md §3.

Observability#

• Sentry captures unhandled exceptions on both client and server. The @sentry/astro integration is activated in astro.config.mjs only when SENTRY_DSN_MEMO is set, so dev environments without the DSN don't ship beacons.

• Vercel runtime logs show every cron invocation. Filter by path to triage.

• Audit logs are queryable via Drizzle:

  SELECT ts, actor_user_id, actor_visitor_email, action, target_type, target_id, meta
  FROM memo.audit_logs
  WHERE ts > now() - interval '1 hour'
  ORDER BY ts DESC;
  

• Visitor events (Mongo time-series) are queryable per-link:

  db.events.find({ link_id: "<uuid>", ts: { $gte: ISODate("...") } }).sort({ ts: 1 });
  

Verify pipeline#

Memo ships with a five-step pre-push gate. Every step is also runnable on its own:

What each step covers#

• type:check — runs astro check, which is tsc plus Astro's .astro file understanding. Catches everything tsc would catch in a Next.js app, plus drift between Astro.params declarations and route file paths.

• test — Vitest is wired in via vitest.config.ts with the same @/* alias that the app uses. Test files live next to their subjects (src/lib/urls.test.ts, src/lib/routing.test.ts, src/lib/validation/link.test.ts, src/lib/visitor/gate.test.ts). Scope is pure modules only — any file that imports a DB / R2 / Redis / Clerk / rrweb-storage adapter is out of the unit-test surface and lives in the route-smoke or live integration runs.

  Coverage by file:

  Test file	Coverage
  src/lib/urls.test.ts	ownerRoot, ownerHref (joining + slash normalisation), visitorHref, visitorStepHref, visitorUrl. Includes guards that the legacy /$/ and /v/ schemes don't drift back in.
  src/lib/routing.test.ts	isVisitorPath over the full canonical route set + parity guard between SLUG_RESERVED and the named app surfaces (every named non-visitor path is reserved).
  src/lib/validation/link.test.ts	linkCreateSchema slug rules (kebab-case, lowercasing, min length, reserved rejection, disallowed chars) + self-consistency of SLUG_RESERVED (no dupes, all lowercase).
  src/lib/visitor/gate.test.ts	nextStep state machine across all gate combinations, emailAllowedByLink allow/block precedence, cookieName sanitisation, setCookieHeader flags (Path=/ for root visitor URLs, HttpOnly, SameSite=Lax, Secure only when secure=true).

• build — astro build with the @astrojs/vercel adapter. Surfaces missing/broken imports that type-check wouldn't.

• verify:routes — a node script (no deps) that enumerates the canonical route↔file map (134 routes / 134 files at last count) and asserts:

  1. Every expected route has a backing page file under src/pages/.
  2. No file lives under a forbidden top-level segment ($/, v/, app/ — historical URL schemes).
  3. No orphan page file exists outside the canonical route map.

  Adding a new page? Update the EXPECTED map in scripts/verify-routes.mjs. The smoke fails loudly if you forget.

• verify — the green-light gate. Always run this before git push. Total ~10 s.

When tests fail#

Local development against prod-like infra#

For end-to-end testing against real Neon + Mongo + R2, point .env.local at staging projects (separate Cloudflare bucket, separate Neon database, separate Clerk app). The dev server (pnpm --filter @matters/memo dev) on port 4004 will pick them up. The cron endpoints can be triggered manually:

curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:4004/api/cron/rotate-jwt-key
curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:4004/api/cron/expire-links

Cost ceiling#

Free-tier limits we've designed against:

• Neon: 0.5 GB row data; 50 owners × 100 projects × 1 KB rows = ~5 MB.
• Mongo Atlas M0: 0.5 GB; 50 visitors/mo × 200 events × 1 KB × 3 months = ~30 MB.
• R2: 10 GB; depends on owner content. Typical demo deck is 1–5 MB.
• Upstash Redis: 256 MB; we use a few KB.
• QStash: 500 messages/day; one per NDA sign = comfortable.
• Resend: 3k emails/mo; OTP-only volume.
• Clerk: 10k MAU; ample.

Above these thresholds memo gets cheaper to upgrade than to engineer around.