kampus-pipeline

phoenix

kamp.us, reborn. A single Cloudflare Worker on alchemy + Effect + fate that serves the SPA, the data plane, and every backend route.

It is not a general-purpose framework. It is the opinionated stack the kamp.us products (sozluk, pano, vote, stats) are built on, written down precisely enough that you can extend it without reverse-engineering the choices.

Quickstart

pnpm install
pnpm dev          # vite (SPA + HMR) + alchemy dev (worker on local workerd)
pnpm typecheck    # effect-tsgo across project references
pnpm deploy       # vite build + alchemy deploy (use --stage <name> for isolation)

alchemy dev runs the worker locally in workerd, but the resources it binds — D1, the live Durable Object — are real Cloudflare resources in your personal dev stage. There is no offline emulator (ADR 0032).

Stack

Layer	Choice	What it does for phoenix
Infra + runtime	alchemy 2.0.0-beta.45	One Effect program declares the worker, its bindings, and the Durable Object. No wrangler.jsonc.
Effect system	[email protected]	Backend control flow, services, layers, errors, tracing.
Data protocol	fate	/fate for data views, /fate/live for live views over SSE. Server types are the schema — no codegen artifact between server and client.
HTTP	effect/unstable/http	HttpApiBuilder for typed JSON groups, imperative HttpRouter for raw-Request and SSE routes. No Hono, no GraphQL.
Auth	@alchemy.run/better-auth	BetterAuth on D1 (magic-link + bearer + email/password) via a forked CloudflareD1 Layer. Session secret comes from the BETTER_AUTH_SECRET binding — no default, fails closed if it is missing.
DB	Drizzle on D1	Drizzle is a worker-level singleton; feature code calls its run/batch capability methods.
Live state	LiveDO on state.storage KV	One Durable Object fans out SSE. State is KV — subscriber rows + a per-connection counter. No DO SQL, no DO migrations.
Frontend	React 19 + Vite 8 + react-fate	Components declare views; one batched useRequest per screen; declarative mutations; live views over SSE.
Type-check	@effect/tsgo	Fast tsc plus Effect's LSP.
Lint / format	Biome 2	Tabs, 100 col, no bracket spacing.
Package manager	pnpm 10 (workspace catalog)	All commands use pnpm; pnpm dlx, never npx.

Architecture

phoenix is a pnpm monorepo with effectively one app — the worker in apps/web. The docs live alongside the code: .decisions/ for the why, .patterns/ for the how.

One worker serves the React SPA (built to dist/client, served via the assets binding) and the API. It keeps precedence on its own paths — /api/*, /fate, /fate/* — and hands everything else to the SPA. The backend is one Effect program: it declares its bindings, hosts the Durable Object, and returns a fetch handler.

apps/web/
├── alchemy.run.ts         # the stack — state mode + the worker resource
└── worker/
    ├── index.ts           # entry — DO host, bindings, layer assembly
    ├── env.ts             # deploy-time env resolution (fails closed)
    ├── db/                # D1 binding, Drizzle schema, migrations, keyset cursors
    ├── http/              # router composition (app.ts) + health route
    └── features/          # every named grouping, one folder each
        ├── fate/          # the fate config + route, layer assembly, barrels
        ├── fate-live/     # the live SSE plane — LiveDO + LivePublisher + protocol
        ├── pasaport/      # auth — better-auth fork + session capability
        ├── sozluk/        # product — dictionary
        ├── pano/          # product — link aggregator
        ├── vote/          # product — votes
        ├── stats/         # product — read-only counts
        └── text/          # utility — excerpt()

features/ is the home for any named app-level grouping — product domains, framework concerns, and single-file utilities alike. If a concern has a coherent name worth grouping, it's a feature; the few things that aren't (entry, env, db, http) sit beside features/ (ADR 0036).