leaflet.pub
a tool for shared writing and social publishing
awarm.space
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7Leaflet is a full-stack TypeScript web app for shared writing and social publishing, built on Bluesky (AT Protocol). Users create collaborative documents ("Leaflets") and publish them as blog posts/newsletters ("Publications") that others can follow.
8
9## Tech Stack
10
11- **Frontend**: React 19 + Next.js 16 (App Router, Turbopack)
12- **Database**: PostgreSQL via Supabase + Drizzle ORM
13- **Real-time sync**: Replicache for optimistic updates and offline support
14- **Editor**: ProseMirror with Yjs CRDT
15- **Social**: AT Protocol (@atproto packages) for Bluesky integration
16- **Jobs**: Inngest for async serverless functions
17
18## Commands
19
20```bash
21npm run dev # Start Next.js dev server (port 3000)
22npm run start-appview-dev # Start AT Protocol appview service
23npm run start-feed-service-dev # Start feed subscription service
24npm run lint # ESLint
25npx tsc # TypeScript type checking (used in CI)
26npm run generate-db-types # Regenerate Supabase types after schema changes
27npm run lexgen # Regenerate AT Protocol types from lexicons
28```
29
30## Architecture
31
32### Data Flow
33
341. **Client mutations** go through Replicache (`src/replicache/mutations.ts`) for optimistic local updates
352. **Server actions** in `actions/` persist changes to Supabase
363. **CVR sync** reconciles client and server state via Replicache
37
38### Document Model
39
40Documents are composed of **blocks** (text, image, embed, code, poll, etc.). Block components live in `components/Blocks/`. Blocks are rendered in linear lists by `components/Blocks/index.tsx` and in an xy canvas by `components/Canvas.tsx`.
41
42### AT Protocol / Bluesky
43
44- **Lexicons** (`lexicons/`) define schemas for reading and writing records to the AT Protocol network and users' PDSs
45- **Appview** (`appview/`) consumes the firehose to index published content
46- **Feeds** (`feeds/`) provides subscription feeds for publications
47
48### Key Directories
49
50- `app/` - Next.js App Router pages and API routes
51- `actions/` - Server actions (mutations, auth, subscriptions)
52- `components/` - React components
53- `src/` - Shared utilities, hooks, Replicache setup
54- `appview/` - AT Protocol firehose consumer for indexing
55- `feeds/` - Feed service for publication subscriptions
56- `lexicons/` - AT Protocol schema definitions
57- `supabase/migrations/` - Database schema
58
59### Patterns
60
61- **Server actions**: Export async functions with `'use server'` directive, return `Result<T>` from `src/result.ts`
62- **Replicache mutations**: Named handlers in `src/replicache/mutations.ts`, keep server mutations idempotent
63- **React contexts**: `DocumentProvider`, `LeafletContentProvider` for page-level data
64- **Inngest functions**: Async jobs in `app/api/inngest/functions/`