Exosphere is a set of small, modular, self-hostable community tools built on the AT Protocol.
app.exosphere.site
1# Exosphere
2
3Modular, self-hostable community platform built on the AT Protocol.
4
5## Tools
6
7- **Runtime & package manager**: Bun (workspaces monorepo)
8- **Backend**: Hono.js on Bun, SQLite via `bun:sqlite`
9- **Frontend**: Preact + Preact Signals, vanilla-extract for styling, Vite for dev/build
10- **Auth**: AT Protocol OAuth (`@atproto/*` packages)
11- **Validation**: Zod at system boundaries
12- **Language**: TypeScript (strict mode)
13- **Dev PDS**: Docker Compose (`docker-compose.dev.yml`) runs a local Bluesky PDS
14
15### Commands
16
17- `bunx run check`: (or `vp check`) Check project lints, tpyes, format
18- `bun run test`: (or `vp test`) Run unit tests
19- `bun run test:e2e`: Run end-to-end tests
20
21## Architecture
22
23Monorepo with Bun workspaces under `packages/`:
24
25| Package | Role |
26| ------------------ | --------------------------------------------------------------------------------------------------------- |
27| `core` | Shared infra: auth, db, sphere management, types |
28| `client` | Shared client-side utilities: API helpers, auth, router, theme, UI styles, reusable components |
29| `app` | Host app — assembles modules, Hono server entry (`src/server.ts`), Preact client entry (`src/client.tsx`) |
30| `feeds` | Feed & discussions module |
31| `feature-requests` | Feature requests module |
32
33Each module exposes: a Hono sub-app (API routes), Preact components (UI), its own SQLite migrations, and a `ExosphereModule` interface. Modules depend on `core` but not on each other.
34
35The `app` package registers modules in `src/server.ts` by mounting their API routes under `/api/<module-name>`.
36
37See `ARCHITECTURE.md` for full details on data flow, AT Protocol integration, membership model, and access modes.
38
39### Lexicons
40
41The project lexicons are located in `../landing` and hosted on tangled:
42https://tangled.org/exosphere.site/landing.
43
44## TS/TSX coding style
45
46- Strong typing and type safety
47- Avoid barrel files when possible
48- We are using Preact, in JSX, prefer `class` over `className`
49- Make optimistic updates when possible
50
51## Styling
52
53- **No universal `box-sizing: border-box`** — let elements use the default `content-box`. Only apply `border-box` on specific elements that need it (e.g. form controls with `width: 100%`).
54- **Prefer CSS logical properties** for margins, paddings, and borders (`margin-inline`, `padding-block`, `border-inline-start`, etc.) over physical properties (`margin-left`, `padding-top`, etc.).
55- **Prefer modern CSS** — use contemporary features and patterns over legacy approaches.
56- Avoid inline styling, prefer re-usable components from ./packages/client