Server Overview

The Cosmo backend is a NestJS REST API server located at packages/server. It serves all desktop, web, and CLI clients through a single API surface.

Technology Stack

Module Map

AppModule
├── AuthModule        — JWT, OAuth, Clerk sync, org management
├── ChatModule        — LLM streaming via SSE
├── WorkspacesModule  — Workspace CRUD
├── TasksModule       — Task management + AI reprioritization
├── TeamsModule       — Team & membership management
├── ConnectorsModule  — MCP connector instances
├── ConnectorProvidersModule — Provider registry
├── MCPOAuthModule    — Server-mediated OAuth for integrations
├── WorkspaceSyncModule — File sync + SSE change feed
├── BillingModule     — Stripe subscriptions + webhooks
├── MeteringModule    — Token usage + quota enforcement
├── UpdatesModule     — Desktop app release management
└── AdminModule       — Internal enterprise + release admin

Startup (main.ts)

On bootstrap:

1. Creates NestJS app with bodyParser: false to allow raw body access for webhook signature verification.
2. Sets up raw body middleware for /api/v1/billing/webhook and /api/v1/auth/webhook (Stripe + Svix need the raw bytes).
3. Configures CORS to allow requests from localhost:3000, localhost:5173, Electron app:// origin, and 127.0.0.1.
4. Sets up Clerk Frontend API proxy at /__clerk/* — forwards to clerk.getcosmo.app with proxy headers. This lets the Electron desktop app load Clerk from localhost.
5. Applies global exception filter (catches unhandled errors, sends 5xx to PostHog).
6. Sets global prefix api/v1.
7. Listens on process.env.PORT ?? 4000.

Auth Model

All endpoints (except webhooks and the public connector-providers list) require a Bearer token in the Authorization header.

Two token types are accepted by ClerkAuthGuard:

When a Clerk JWT is presented, the guard syncs user/org/membership data from Clerk into the local DB on first use. The guard attaches a RequestUser object to req.user:

interface RequestUser {
  userId: string;
  orgId: string;
  orgRole: OrgRole;
}

Tenant Isolation

Every query, every endpoint, every WebSocket message is scoped to orgId. There is no cross-tenant data access. The orgId is always derived from the verified JWT — it cannot be supplied by the client.

Storage Architecture

All file content lives in R2/S3 blob storage. PostgreSQL is a metadata index only — it holds StorageObject records with a storageKey (the blob key) but never the file bytes.

/{orgId}/shared/hub-memory/          ← Org-level hub memory
/{orgId}/shared/brand/               ← Brand assets
/{orgId}/shared/templates/           ← Shared templates
/{orgId}/teams/{teamId}/memory/      ← Team memory
/{orgId}/workspaces/{workspaceId}/   ← Workspace artifacts + memory
/{orgId}/personal/{userId}/          ← Personal drafts, user memory

Error Handling

GlobalExceptionFilter catches all unhandled exceptions:

• Returns { statusCode, message, timestamp, path } JSON.
• Sends only 5xx errors to PostHog (4xx errors are user mistakes, not bugs).

Environment Variables