From 575852c1242375027e4db3d6d63f8d3eb0e50240 Mon Sep 17 00:00:00 2001 From: Julien Calixte Date: Mon, 9 Feb 2026 21:14:23 +0100 Subject: [PATCH] chore: add CLAUDE.md with project guidance for Claude Code Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7c3000b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,44 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +litenote-jetstream is the backend for Litenote, a blogging platform built on the AT Protocol (Bluesky ecosystem). It has two processes: + +1. **Jetstream listener** (`jetstream.ts`) — Subscribes to the AT Protocol firehose via `@skyware/jetstream`, filtering for `space.litenote.note` records. On create/update events, it upserts notes into a local SQLite database. +2. **HTTP API server** (`server.ts`) — An Oak (Deno HTTP framework) server on port 8080 that exposes read-only endpoints to query stored notes. + +Both processes share the same SQLite database (`src/data/db.ts`). + +## Commands + +```bash +# Run jetstream listener (dev, with watch) +deno task jetstream + +# Run API server (dev, with watch) +deno task server + +# Run both for production (as in Docker) +deno task jetstream:prod & deno task server:prod + +# Run database migration +deno task migrate + +# Lint +deno lint + +# Format +deno fmt +``` + +## Architecture + +- **Runtime**: Deno (not Bun, despite the README). Uses `deno.json` for task definitions and import maps. +- **Database**: SQLite via `https://deno.land/x/sqlite/mod.ts`. DB path is configurable via `SQLITE_PATH` env var, defaults to `notes.db`. +- **Note schema**: Defined as an AT Protocol lexicon in `lexicons/space/litenote/note.json`. Notes have `title`, `content` (markdown), optional `images` (blob refs), `publishedAt`, and `createdAt`. Primary key is `(did, rkey)`. +- **API endpoints**: + - `GET /notes?cursor=&limit=` — paginated notes (all users) + - `GET /:did/notes?cursor=&limit=` — paginated notes for a specific DID +- **Pagination**: cursor-based using `rkey`, descending order.