Architecture

The 30-second version

Three interfaces carry the whole design:

• StorageAdapter - durable reads/writes (conversations, messages, read-state). Core depends on the interface, never on a specific database.
• Transport - publish/subscribe of live events to connected SSE clients. The engine publishes only after the storage write succeeds (durable-first). The default is in-process (one node); swap in @chatpack/transport-redis for several. Either way the SSE endpoint recovers missed messages on reconnect from storage via Last-Event-ID.
• PresenceStore - expiring SSE connection leases and global online/offline transitions. The default is process-local; use redisPresenceStore() with the Redis transport for multi-node presence (ADR 0025).

The core engine (@chatpack/core) contains all domain logic: 1:1 and group conversations, membership and role rules, permission checks, validation. Adapters contain no domain logic - they only persist and retrieve.

Request flow

Your frontend  ──  fetch("/api/chat/…")  +  EventSource("/api/chat/stream")
      │
      ▼
chat.handler()        one Web-standard handler (Request → Response)
      │
      ├── auth hook   your session → { id: userId }     (you own users)
      ▼
chat.api.*            domain logic, permissions         (also callable directly)
      │
      ▼
StorageAdapter        memory · Drizzle/Postgres · Supabase · your own
      │
      ▼
Your database

Every HTTP request follows the same path:

1. The handler parses the request. It's a single Web-standard function (Request → Response) that serves every route under basePath (default /api/chat) - including the SSE stream.
2. Your auth hook resolves the current user. Auth runs before routing - an unauthenticated request to a wrong path still gets a 401.
3. chat.api.* applies domain rules: input validation, participant checks, permission hooks, sender-only edit/delete, admin-only group management.
4. The storage adapter persists and retrieves. It never enforces permissions - core already did.
5. For writes, the engine publishes an event on the transport after the storage write succeeds, and connected SSE streams deliver it.

What lives where

One instance, everywhere

Create the chatpack() instance in a single module and import it into the route file - never one instance per route. Under dev-server HMR (Vite, next dev), guard it with globalThis so module re-evaluation doesn't reset in-memory state:

import { chatpack, type ChatpackInstance } from "@chatpack/core";

const g = globalThis as typeof globalThis & { __chatpack__?: ChatpackInstance };
export const chat = (g.__chatpack__ ??= chatpack({ storage, auth }));

Configuration

Everything is configured through the single chatpack() factory:

import { chatpack } from "@chatpack/core";
import { typing, presence, receipts } from "@chatpack/core/plugins";

const chat = chatpack({
  storage: memoryAdapter(), // required - the only required option
  auth: async (req) => resolveUser(req), // required for HTTP; api.* takes explicit ids
  permissions: { canRead, canWrite, canManage }, // defaults: participants; admins for canManage
  hooks: { beforeMessageSend, afterMessageMutation }, // default: none
  plugins: [typing(), presence(), receipts()], // default: none
  transport: inProcessTransport(), // default: in-process; redisTransport() for multi-node
  telemetry: true, // default: true (opt-out)
});

Design rationale (ADRs)

Non-obvious decisions are recorded as short ADRs in docs/decisions/: