Architecture

A bird's-eye view of the Matters AI system and how requests, data, and people flow through it.

Topology#

                                ┌──────────────────┐
                                │  Clerk (auth)    │
                                └────┬─────────────┘
                                     │ cookies (.matters.ai)
                                     ▼
       Public visitor ───►  matters.ai            workspace.matters.ai  ◄─── Internal user
                            (repo root, Vercel)    (apps/workspace, Vercel)
                                  │                       │
                                  │                       │
                                  ├───────► WordPress ◄───┤   (content + settings)
                                  │                       │
                                  ├───────► MongoDB Atlas ┤   (leads, audit logs, glossary, …)
                                  │                       │
                                  ├───────► Upstash Redis ┤   (cache, glossary analytics)
                                  │                       │
                                  └───────► Mux, Sentry, Slack, MailerLite, Resend/SES, Salesforce

Apps#

App	Origin	Purpose	Auth model
Public website (repo root — a future `apps/web` move is planned, see Monorepo → Migration)	`matters.ai`, `www.matters.ai`	Marketing, blog, glossary, careers, gated downloads, lead capture.	None for content; gated forms hit MongoDB-backed APIs.
Workspace (`apps/workspace`)	`workspace.matters.ai`	Internal admin & content studio across 19 modules.	Clerk session + email domain allowlist + per-route RBAC.
Docs (`apps/webdocs`)	`webdocs.matters.ai`	This site. Engineer-facing documentation.	Public by default; can be locked behind Clerk if/when needed.

Shared packages#

Package	What it owns
`@matters/auth`	Email domain allowlist. Future: re-exports of `lib/auth/rbac*`.
`@matters/lib`	Errors, logger, `env` (Zod-validated), Sentry config, `cn` Tailwind helper.
`@matters/ui`	Scaffold today — destination for the Radix-based primitives in `components/ui/`.
`@matters/config`	Shared `tsconfig.base.json` and `tsconfig.next.json`.
`@matters/theme`	Runtime multi-variant theme system (12 variants, light + dark). Consumed by workspace, partners, webdocs.

The public website still consumes the root components/, lib/, hooks/ directories directly. The workspace consumes the same paths via a tsconfig path bridge until those modules graduate into shared packages — see Monorepo → Migration History for context.

Request lifecycle (workspace)#

Browser sends request to workspace.matters.ai/<route>.
Vercel routes to apps/workspace.
apps/workspace/proxy.ts runs:
- Public routes (/auth/*, /api/webhooks/clerk, /api/health) pass through.
- Everything else requires a Clerk session and an allowlisted email domain. Failures redirect to the login flow (or return 401/403 for API routes).
The matching route.ts or page.tsx runs. Pages re-check the allowlist + fetch RBAC roles in their layout (defense-in-depth). API handlers call checkRole(...) against lib/auth/rbac-shared.ts.

Request lifecycle (public website)#

Browser sends request to matters.ai/<route>.
Vercel routes to the repo root (the public Next.js app).
Root proxy.ts runs: AI-crawler tracking + security headers. No auth gate (the protected matcher is intentionally empty — protected routes live on the workspace subdomain).
Page renders. Most content is RSC + WordPress fetch + MongoDB lookups. Marketing forms post to app/api/* handlers which themselves don't require auth but do server-side validation and write to MongoDB.

Where to dig deeper#

The codebase tour: Monorepo → Layout & Packages.
Auth deep-dive: Workspace → Authentication.
Permission matrix: Workspace → RBAC.
Every env var: Operations → Environment Variables.

Loading…

Topology#

                                ┌──────────────────┐
                                │  Clerk (auth)    │
                                └────┬─────────────┘
                                     │ cookies (.matters.ai)
                                     ▼
       Public visitor ───►  matters.ai            workspace.matters.ai  ◄─── Internal user
                            (repo root, Vercel)    (apps/workspace, Vercel)
                                  │                       │
                                  │                       │
                                  ├───────► WordPress ◄───┤   (content + settings)
                                  │                       │
                                  ├───────► MongoDB Atlas ┤   (leads, audit logs, glossary, …)
                                  │                       │
                                  ├───────► Upstash Redis ┤   (cache, glossary analytics)
                                  │                       │
                                  └───────► Mux, Sentry, Slack, MailerLite, Resend/SES, Salesforce

Apps#

App	Origin	Purpose	Auth model
Public website (repo root — a future `apps/web` move is planned, see Monorepo → Migration)	`matters.ai`, `www.matters.ai`	Marketing, blog, glossary, careers, gated downloads, lead capture.	None for content; gated forms hit MongoDB-backed APIs.
Workspace (`apps/workspace`)	`workspace.matters.ai`	Internal admin & content studio across 19 modules.	Clerk session + email domain allowlist + per-route RBAC.
Docs (`apps/webdocs`)	`webdocs.matters.ai`	This site. Engineer-facing documentation.	Public by default; can be locked behind Clerk if/when needed.

Shared packages#

Package	What it owns
`@matters/auth`	Email domain allowlist. Future: re-exports of `lib/auth/rbac*`.
`@matters/lib`	Errors, logger, `env` (Zod-validated), Sentry config, `cn` Tailwind helper.
`@matters/ui`	Scaffold today — destination for the Radix-based primitives in `components/ui/`.
`@matters/config`	Shared `tsconfig.base.json` and `tsconfig.next.json`.
`@matters/theme`	Runtime multi-variant theme system (12 variants, light + dark). Consumed by workspace, partners, webdocs.

The public website still consumes the root components/, lib/, hooks/ directories directly. The workspace consumes the same paths via a tsconfig path bridge until those modules graduate into shared packages — see Monorepo → Migration History for context.

Request lifecycle (workspace)#

Browser sends request to workspace.matters.ai/<route>.

Vercel routes to apps/workspace.

apps/workspace/proxy.ts runs:

Public routes (/auth/*, /api/webhooks/clerk, /api/health) pass through.
Everything else requires a Clerk session and an allowlisted email domain. Failures redirect to the login flow (or return 401/403 for API routes).

The matching route.ts or page.tsx runs. Pages re-check the allowlist + fetch RBAC roles in their layout (defense-in-depth). API handlers call checkRole(...) against lib/auth/rbac-shared.ts.

Request lifecycle (public website)#

Browser sends request to matters.ai/<route>.

Vercel routes to the repo root (the public Next.js app).

Root proxy.ts runs: AI-crawler tracking + security headers. No auth gate (the protected matcher is intentionally empty — protected routes live on the workspace subdomain).

Page renders. Most content is RSC + WordPress fetch + MongoDB lookups. Marketing forms post to app/api/* handlers which themselves don't require auth but do server-side validation and write to MongoDB.