From a7114a00b1dae63d56ab95e2f17965da9031f56b Mon Sep 17 00:00:00 2001 From: Florian <45694132+flo-bit@users.noreply.github.com> Date: Fri, 24 Apr 2026 13:15:54 +0200 Subject: [PATCH] ordering, add examples --- README.md | 11 ++-- docs/{indexing.md => 01-indexing.md} | 6 +- docs/{spaces.md => 02-spaces.md} | 0 docs/{communities.md => 03-communities.md} | 2 +- docs/{sync.md => 04-sync.md} | 2 +- docs/{lexicons.md => 05-lexicons.md} | 0 docs/06-examples.md | 65 ++++++++++++++++++++++ 7 files changed, 76 insertions(+), 10 deletions(-) rename docs/{indexing.md => 01-indexing.md} (94%) rename docs/{spaces.md => 02-spaces.md} (100%) rename docs/{communities.md => 03-communities.md} (97%) rename docs/{sync.md => 04-sync.md} (97%) rename docs/{lexicons.md => 05-lexicons.md} (100%) create mode 100644 docs/06-examples.md diff --git a/README.md b/README.md index 916ee53..28adadf 100644 --- a/README.md +++ b/README.md @@ -40,11 +40,12 @@ export default { fetch: createHandler(contrail) }; ## Docs -- [Indexing](./docs/indexing.md) — the core: collections, queries, ingestion, adapters -- [Spaces](./docs/spaces.md) — permissioned records stored by the appview -- [Communities](./docs/communities.md) — group-controlled atproto DIDs -- [Sync](./docs/sync.md) — reactive client-side store over `watchRecords` -- [Lexicons](./docs/lexicons.md) — `contrail-lex` CLI and codegen +- [Indexing](./docs/01-indexing.md) — the core: collections, queries, ingestion, adapters +- [Spaces](./docs/02-spaces.md) — permissioned records stored by the appview +- [Communities](./docs/03-communities.md) — group-controlled atproto DIDs +- [Sync](./docs/04-sync.md) — reactive client-side store over `watchRecords` +- [Lexicons](./docs/05-lexicons.md) — `contrail-lex` CLI and codegen +- [Examples](./docs/06-examples.md) — reference deployments in the repo ## Packages diff --git a/docs/indexing.md b/docs/01-indexing.md similarity index 94% rename from docs/indexing.md rename to docs/01-indexing.md index 244899a..9f22c70 100644 --- a/docs/indexing.md +++ b/docs/01-indexing.md @@ -91,6 +91,6 @@ const db = createPostgresDatabase(pool); | `jetstreams` | Bluesky | Jetstream URLs | | `relays` | Bluesky | Relay URLs for discovery | | `notify` | off | `true` opens `notifyOfUpdate`; a string requires `Bearer` | -| `spaces` | — | See [Spaces](./spaces.md) | -| `community` | — | See [Communities](./communities.md) | -| `realtime` | — | See [Sync](./sync.md) | +| `spaces` | — | See [Spaces](./02-spaces.md) | +| `community` | — | See [Communities](./03-communities.md) | +| `realtime` | — | See [Sync](./04-sync.md) | diff --git a/docs/spaces.md b/docs/02-spaces.md similarity index 100% rename from docs/spaces.md rename to docs/02-spaces.md diff --git a/docs/communities.md b/docs/03-communities.md similarity index 97% rename from docs/communities.md rename to docs/03-communities.md index af2c1db..c07d517 100644 --- a/docs/communities.md +++ b/docs/03-communities.md @@ -1,6 +1,6 @@ # Communities -Group-controlled atproto DIDs. A community is a DID whose signing/rotation keys are held by the appview on behalf of multiple members, with tiered access levels. Built on top of [spaces](./spaces.md). +Group-controlled atproto DIDs. A community is a DID whose signing/rotation keys are held by the appview on behalf of multiple members, with tiered access levels. Built on top of [spaces](./02-spaces.md). ## When to use this diff --git a/docs/sync.md b/docs/04-sync.md similarity index 97% rename from docs/sync.md rename to docs/04-sync.md index e2e29e1..d0419dc 100644 --- a/docs/sync.md +++ b/docs/04-sync.md @@ -78,7 +78,7 @@ realtime: { } ``` -See [indexing.md](./indexing.md) for the full config surface. +See [Indexing](./01-indexing.md) for the full config surface. ## Lifecycle diff --git a/docs/lexicons.md b/docs/05-lexicons.md similarity index 100% rename from docs/lexicons.md rename to docs/05-lexicons.md diff --git a/docs/06-examples.md b/docs/06-examples.md new file mode 100644 index 0000000..4445cd7 --- /dev/null +++ b/docs/06-examples.md @@ -0,0 +1,65 @@ +# Examples + +Every example lives in [`apps/`](https://github.com/flo-bit/contrail/tree/main/apps) and pins contrail as `workspace:*`. Clone the repo, `pnpm install`, and each one runs. + +## `rsvp-atmo` — the reference deployment + +[`apps/rsvp-atmo`](https://github.com/flo-bit/contrail/tree/main/apps/rsvp-atmo) + +Cloudflare Workers + D1. Indexes `community.lexicon.calendar.event` and `rsvp`. Exposes the full spaces + community + realtime surface. Cron-driven Jetstream ingestion every minute. + +Use this if you're building on Workers and want a starting point that already has deploy config wired up. + +```bash +pnpm --filter rsvp-atmo dev # local wrangler + auto-cron +pnpm --filter rsvp-atmo deploy # requires D1 database created +pnpm --filter rsvp-atmo sync # discover + backfill against D1 +``` + +## `group-chat` — full app showcase + +[`apps/group-chat`](https://github.com/flo-bit/contrail/tree/main/apps/group-chat) + +SvelteKit + Cloudflare Workers. The one that exercises everything: permissioned spaces for private rooms, community-controlled DIDs for groups, client-side `contrail-sync` for reactive messages, Durable Object-hibernated WebSockets for realtime delivery, OAuth-based login. + +This is the canonical "what can contrail do" demo. If you're trying to understand how the pieces fit together end to end, read this app's code before anything else. + +```bash +pnpm --filter sveltekit-group-chat dev +``` + +## `postgres` — Node + PG minimal + +[`apps/postgres`](https://github.com/flo-bit/contrail/tree/main/apps/postgres) + +The smallest possible Node deployment. Docker Compose for Postgres, three scripts: `sync` (discover + backfill), `ingest` (persistent Jetstream), `serve` (HTTP handler). Skips spaces/communities/realtime. + +Use this as a template if you're running on a normal server and don't need Cloudflare's bells. + +```bash +cd apps/postgres +docker compose up -d +pnpm sync +pnpm serve +``` + +## `cloudflare-workers` — minimal Workers + +[`apps/cloudflare-workers`](https://github.com/flo-bit/contrail/tree/main/apps/cloudflare-workers) + +The simplest working Worker. One collection (events), one HTTP handler, cron-driven ingest. No spaces, no communities. Good for reading top-to-bottom in one sitting to see what contrail does at minimum. + +## `sveltekit-cloudflare-workers` — SvelteKit Statusphere + +[`apps/sveltekit-cloudflare-workers`](https://github.com/flo-bit/contrail/tree/main/apps/sveltekit-cloudflare-workers) + +A Statusphere-style SvelteKit app with OAuth login, contrail-indexed public records, and Cloudflare adapter. No spaces/communities — think "atproto blog or status post UI." Useful as a scaffold for public-only apps. + +## Choosing a starting point + +| Need | Start from | +|---|---| +| "Just index some records" | `cloudflare-workers` or `postgres` | +| "Index + SvelteKit UI, public only" | `sveltekit-cloudflare-workers` | +| "Private rooms / group chat / full stack" | `group-chat` | +| "Calendar-ish domain, Workers deploy" | `rsvp-atmo` | -- 2.51.2