WIP: Just extracted most of the parts from CourseLit

Author: Rajat

.gitignore

@@ -0,0 +1,5 @@
+# Dependencies
+node_modules/
+
+# Build
+dist/

AGENTS.md

@@ -0,0 +1,3 @@
+## Development Tips
+- Don't duplicate stuff over and over. Re-use existing code and libraries.
+- For UI components, use shadcn/ui exclusively.

ARCHITECTURE.md

@@ -0,0 +1,3 @@
+## Development Tips
+- Don't duplicate stuff over and over. Re-use existing code and libraries.
+- For UI components, use shadcn/ui exclusively.

CLAUDE.md

@@ -0,0 +1,45 @@
+# SendLit
+Open-source email marketing platform
+
+## Tech stack
+- TypeScript
+- PostgreSQL
+- Redis
+- Bull MQ
+- Nextjs
+- Tailwind CSS
+- shadcn/ui
+
+## Status
+
+SendLit is being bootstrapped by extracting the email composing/sending/
+automation capabilities out of [CourseLit](https://github.com/codelitdev/courselit)
+and reusing the OAuth2 implementation from
+[MediaLit](https://github.com/codelitdev/medialit)'s API. See
+[`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full migration plan. `apps/api`
+(including its MCP server), `packages/email-editor`, `packages/email-blocks`
+and `apps/web` are built and have been validated end-to-end (OAuth login,
+contacts, templates, broadcasts and sequences, including the automation/
+delivery loop, and raw JSON-RPC calls against the MCP server). Account-wide
+analytics, bounce handling and multi-user accounts are still on the roadmap.
+
+## Packages
+
+- `apps/api` — OAuth2-protected REST API: contacts, templates, broadcasts/
+  sequences, mail sending and automation.
+- `apps/web` — the dashboard UI (Next.js): sign in, manage contacts, compose
+  templates/broadcasts/sequences, start/pause automations.
+- `packages/email-editor` — the WYSIWYG email editor (`@sendlit/email-editor`).
+- `packages/email-blocks` — headless composing blocks for broadcasts/
+  sequences/templates (`@sendlit/email-blocks`), used by `apps/web`.
+
+## Running everything locally
+
+1. Start Postgres and Redis (e.g. via Docker).
+2. `apps/api`: copy `.env.example` to `.env`, fill in the values, then
+   `pnpm --filter @sendlit/api db:push` and `pnpm --filter @sendlit/api dev`.
+3. `apps/web`: copy `.env.example` to `.env.local` (`API_URL` pointing at the
+   API above), then `pnpm --filter @sendlit/web dev`.
+4. Build the two shared packages at least once so `apps/web` has something to
+   import: `pnpm --filter @sendlit/email-editor build && pnpm --filter @sendlit/email-blocks build`
+   (re-run, or use their `dev` scripts, after changing either package).

README.md

@@ -0,0 +1,45 @@
+# Postgres connection string
+DB_CONNECTION_STRING=postgres://sendlit:sendlit@localhost:5432/sendlit
+
+# Redis (used by BullMQ for mail sending + sequence delivery)
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+PORT=4000
+NODE_ENV=development
+
+# OAuth2 JWT signing key — must be at least 32 bytes. Generate with:
+#   openssl rand -base64 48
+OAUTH_SIGNING_KEY=
+
+# Used to sign open/click tracking pixel tokens.
+PIXEL_SIGNING_SECRET=
+
+# Encrypts per-team ESP (SMTP) credentials at rest (AES-256-GCM). Must decode
+# to 32 bytes (base64) or contain at least 32 bytes (utf8). Generate with:
+#   openssl rand -base64 32
+ESP_CREDENTIALS_ENCRYPTION_KEY=
+
+# Used to build tracking-pixel/click/unsubscribe links embedded in outgoing mail.
+PROTOCOL=https
+DOMAIN=
+
+# Platform default mail transport, used when a team hasn't configured its own
+# ESP (see src/esp/*, src/mail/transport.ts).
+EMAIL_HOST=
+EMAIL_PORT=587
+EMAIL_USER=
+EMAIL_PASS=
+EMAIL_FROM=
+
+# Optional: on boot, if set and no account exists for this email yet, creates
+# one (with its default team + API key) and logs the key once — a dev/
+# self-host convenience, mirroring MediaLit's admin-bootstrap script. See
+# src/bootstrap.ts.
+SUPER_ADMIN_EMAIL=
+
+# Required to use POST /provisioning/teams — the server-to-server endpoint a
+# multi-tenant consumer (e.g. CourseLit) uses to provision one SendLit team
+# per one of its own tenants. Generate a long random value and configure it
+# identically on both sides. See src/provisioning/routes.ts.
+PROVISIONING_SECRET=

apps/api/.env.example

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.local
+drizzle
+*.log

apps/api/.gitignore

@@ -0,0 +1,52 @@
+FROM node:24-alpine AS base
+RUN corepack enable pnpm
+
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json ./
+COPY pnpm-lock.yaml ./
+COPY pnpm-workspace.yaml ./
+COPY apps/api ./apps/api
+COPY packages/api-contract ./packages/api-contract
+COPY packages/email-editor ./packages/email-editor
+
+RUN pnpm install --frozen-lockfile
+
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/ ./
+
+RUN pnpm --filter=@sendlit/email-editor build
+RUN pnpm --filter=@sendlit/api-contract build
+RUN pnpm --filter=@sendlit/api build
+
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nodeuser
+
+COPY --chown=nodeuser:nodejs --from=builder /app/package.json ./
+COPY --chown=nodeuser:nodejs --from=builder /app/pnpm-lock.yaml ./
+COPY --chown=nodeuser:nodejs --from=builder /app/pnpm-workspace.yaml ./
+
+COPY --chown=nodeuser:nodejs --from=builder /app/packages/email-editor/package.json ./packages/email-editor/package.json
+COPY --chown=nodeuser:nodejs --from=builder /app/packages/email-editor/dist ./packages/email-editor/dist
+
+COPY --chown=nodeuser:nodejs --from=builder /app/packages/api-contract/package.json ./packages/api-contract/package.json
+COPY --chown=nodeuser:nodejs --from=builder /app/packages/api-contract/dist ./packages/api-contract/dist
+
+COPY --chown=nodeuser:nodejs --from=builder /app/apps/api/package.json ./apps/api/package.json
+COPY --chown=nodeuser:nodejs --from=builder /app/apps/api/dist ./apps/api/dist
+
+RUN pnpm install --prod --frozen-lockfile --ignore-scripts
+
+USER nodeuser
+
+EXPOSE 3001
+
+CMD ["node", "apps/api/dist/src/index.js"]

apps/api/Dockerfile

@@ -0,0 +1,119 @@
+# Introduction
+
+This API provides email automation.
+
+## Capabilities
+
+- Composing transactional mails, broadcasts, sequences and templates
+- Managing (CRUD) contacts, including tag/subscription/email-based segmentation
+- Sending emails (BullMQ + nodemailer), through a per-team ESP if configured
+- Automation based on events (tag added/removed, new subscriber, scheduled broadcasts)
+- Email open/click tracking and unsubscribe handling
+- Per-team ESP (email sending provider) configuration and test sends
+- Teams: an OAuth account can own/belong to any number of teams; every other
+  resource (contacts, templates, sequences, ESP config, API keys) is scoped to
+  a team, not the account — see "Teams" below.
+
+## Architecture
+
+- The API is protected by OAuth2 (PKCE, dynamic client registration, email-OTP
+  passwordless login, JWT access/refresh tokens) — ported from
+  [MediaLit's API](../../../medialit/apps/api/src/oauth). See
+  `../../ARCHITECTURE.md` for the full mapping.
+- REST endpoints for contacts, templates, sequences/broadcasts — defined once
+  as a `ts-rest` contract (`packages/api-contract`, `@sendlit/api-contract`),
+  not hand-annotated per route. That contract is the single source of truth
+  for request/response validation (`@ts-rest/express`, at runtime), the
+  OpenAPI document (`@ts-rest/open-api`, see `src/swagger-generator.ts`), and
+  `apps/web`'s typed client (`@ts-rest/core`) — so the docs can't describe a
+  shape the server doesn't actually accept/return. Every `routes.ts` in this
+  app is a *thin adapter*: it extracts `params`/`query`/`body` (already
+  validated) and delegates to the unchanged, framework-agnostic functions in
+  that domain's `queries.ts`, which holds all the actual business logic. If
+  Express is ever swapped for something else, only these adapter files
+  should need to change.
+- Two always-running loops (`src/automation/start.ts`):
+  - `process-rules.ts` — fires date-scheduled broadcasts
+  - `process-ongoing-sequences.ts` — polls due sequence/broadcast deliveries and
+    hands them to a BullMQ queue, processed by `process-ongoing-sequence.ts`
+    (renders the email, adds an open-tracking pixel + click-tracked links,
+    sends it, and schedules the next email)
+- Tag/subscriber-added triggers are event-driven (`automation/fire-event.ts`),
+  called directly from the contacts routes instead of being polled.
+- An OAuth/API-key-protected MCP server (`POST /mcp`), ported from
+  [MediaLit's MCP server](../../../medialit/apps/api/src/mcp) — exposes the same
+  contacts/templates/sequences/ESP/team capabilities as the REST API as MCP
+  tools (see `src/mcp/tools/*`).
+- Each team can configure its own ESP (`src/esp/*`): any provider that
+  exposes an SMTP relay works (SendGrid, Mailgun, Postmark, SES, Resend, or a
+  custom server). Credentials are encrypted at rest
+  (`src/utils/secret-crypto.ts`, AES-256-GCM) and never returned to clients.
+  `src/mail/transport.ts` resolves the right transporter per team, falling
+  back to the platform's `EMAIL_HOST`/etc when a team hasn't configured one.
+
+### Teams
+
+- An `account` (`src/account/*`) is purely a login identity (one email = one
+  account, OTP-based). Every other resource is scoped by `teamId`
+  (`src/team/*`), not `accountId` — a team is the actual tenant/data-scope,
+  and holds its own sending identity (from name/email, mailing address) and
+  mail quota.
+- Every account gets a default team on creation, and can create as many more
+  as it wants (`POST /teams`). An account can belong to several teams
+  (`team_members`, currently always with role `owner` — member invitations
+  are a follow-up).
+- **API keys are team-scoped, not account-scoped** — a team can hold several,
+  independently named/revocable keys (`src/apikey/*`, `POST/GET/DELETE
+  /teams/:teamId/keys`). A key always resolves to exactly one team; there's no
+  ambiguity for API/MCP clients authenticated this way.
+- **OAuth-authenticated (browser) requests** resolve their team from an
+  explicit `X-Sendlit-Team-Id` header, validated against team membership on
+  every call (`src/auth/require-team.ts`) — this is what lets the web
+  dashboard switch teams instantly, without re-authenticating. If the header
+  is omitted and the account belongs to exactly one team, that team is used
+  automatically.
+- `POST /provisioning/teams` is a separate, secret-guarded, server-to-server
+  endpoint for multi-tenant consumers (e.g. CourseLit provisioning one SendLit
+  team per one of its own tenants) to find-or-create a team at any point after
+  both stacks have booted, keyed by a consumer-supplied `externalId` rather
+  than email (a consumer's own tenants may share an owner email) — see
+  `src/provisioning/routes.ts`.
+- `SUPER_ADMIN_EMAIL` is a *different*, boot-time-only convenience (mirrors
+  MediaLit's admin-bootstrap script): on startup, if set and no account exists
+  for it yet, creates one (with its default team + key) and logs the key once
+  — useful for local dev/self-hosting, not for provisioning a multi-tenant
+  consumer's many tenants over time.
+
+See the root [`ARCHITECTURE.md`](../../ARCHITECTURE.md) for what has been
+ported from CourseLit/MediaLit so far and what's still on the roadmap.
+
+## Environment variables
+
+See `.env.example`.
+
+## Running the app
+
+1. Start Postgres and Redis (e.g. via Docker).
+2. Copy `.env.example` to `.env` and fill in the values.
+3. Push the schema to your database: `pnpm --filter @sendlit/api db:push`
+4. Start the server: `pnpm --filter @sendlit/api dev`
+
+The API listens on `PORT` (default `80`) and exposes:
+
+- `GET /health` — liveness check
+- `GET /openapi.json`, `GET /docs` — OpenAPI spec / Swagger UI
+- `GET /.well-known/oauth-authorization-server` — OAuth2 metadata
+- `GET/POST/PATCH/DELETE /teams`, `/teams/:teamId` — team management
+  (OAuth-authenticated only)
+- `GET/POST/DELETE /teams/:teamId/keys` — API keys for a team
+- `POST /contacts`, `GET /contacts`, ... — contacts
+- `POST /templates`, `GET /templates`, ... — email templates
+- `POST /sequences`, `GET /sequences`, ... — broadcasts & sequences
+- `GET /track/open`, `GET /track/click`, `GET /unsubscribe/:token` — tracking
+- `GET/PUT/DELETE /esp-config`, `POST /esp-config/test` — per-team ESP config
+- `POST /provisioning/teams` — server-to-server team provisioning for
+  multi-tenant consumers (guarded by `X-Sendlit-Provisioning-Secret`, not
+  OAuth/API-key auth)
+- `POST /mcp` — MCP server (JSON-RPC over HTTP, `Mcp-Session-Id` header for
+  session continuation); authenticate the same way as REST (`Authorization:
+  Bearer <token>` or `x-sendlit-apikey`)

apps/api/README.md

@@ -0,0 +1,10 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+    schema: "./src/db/schema.ts",
+    out: "./drizzle",
+    dialect: "postgresql",
+    dbCredentials: {
+        url: process.env.DB_CONNECTION_STRING || "",
+    },
+});