Meridian Flow

Meridian Flow is a TypeScript-first writing platform for fiction writers managing long-running web serials. The v3 rebuild keeps the full-stack monorepo shape: thin deployable apps, domain packages for shared contracts and persistence, explicit server domains, and repo-level tooling for local dev, CI, smoke checks, and deployment scaffolding.

For setup, see DEVELOPMENT.md. For product context, see PRODUCT.md, DESIGN.md, and the project knowledge base.

Shared packages

Package	Role
@meridian/contracts	Shared wire types, branded IDs, protocol events, thread DTOs, work/project contracts, interrupt/checkpoint types, and agent metadata.
@meridian/database	Drizzle schema, migrations, PL/pgSQL functions, and Postgres connection helpers for the Drizzle-backed local/runtime database.
@meridian/design-tokens	Warm-paper design token package for colors, typography, spacing, and shared primitives.
@meridian/prosemirror-schema	Shared ProseMirror structural contract for TipTap/Yjs document editing.

Domain runtime lives in apps/server/server/domains/, not in package route handlers. See AGENTS.md for the active layout rules.

Workspace layout

• apps/app/ — authenticated writing workspace (TanStack Start + React + TipTap)
• apps/server/ — Nitro API/WebSocket service: auth boundary, thread endpoints, orchestration, collaboration, packages, billing, storage, and server domains
• apps/www/ — public marketing site
• packages/ — shared TypeScript libraries
• tools/ — local dev, CI, deployment, smoke-test, and migration tooling
• tests/smoke/ — operator-facing smoke checks and browser/manual runbooks

Quickstart

pnpm install
pnpm dev:infra       # start the Postgres Docker container (postgres:16 + pg_bigm)
pnpm bootstrap       # create the DB, migrate, apply-functions
pnpm dev

Dev is portless: use pnpm portless:list for live https://*.localhost URLs instead of hard-coded raw ports.

Verification

pnpm check
MODEL_PROVIDER=mock pnpm exec tsx tests/smoke/run.ts
pnpm --filter @meridian/server smoke:thread-runtime

Database schema changes are generated by Drizzle in packages/database; local Postgres is a Docker container built from tools/postgres/Dockerfile (postgres:16 plus pg_bigm). Auth is WorkOS AuthKit with app-owned public.users.

Pull requests

Open PRs against main using the repo pull request template and fill every section before merge, writing "None." with a reason where one doesn't apply; tools/ci/check-pr-body.mjs enforces the sections. Every PR keeps the long-term direction in view: Core design decisions names what it settles, and Goal opens with the long-term goal it serves.

Canonical docs policy

Repo-root docs are pointer-oriented. Durable product decisions live in the Meridian knowledge base; local .context/ files capture implementation-near facts that agents should read before changing code.