WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
1# atBB
2
3**A BB-style forum, on the ATmosphere!**
4
5atBB is a decentralized forum built on the [AT Protocol](https://atproto.com/). Users authenticate with their AT Proto identity (DID) and own their posts on their own Personal Data Server (PDS). The forum's AppView subscribes to the network firehose, indexes relevant records, and serves them through a web interface.
6
7- **Domain:** [atbb.space](https://atbb.space)
8- **Lexicon namespace:** `space.atbb.*`
9- **License:** AGPL-3.0
10- **Organization:** [atBB-Community](https://github.com/atBB-Community)
11
12## Architecture
13
14```
15┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
16│ Forum UI │────▶│ AppView │────▶│ Firehose / │
17│ (Web App) │◀────│ (Node/TS) │◀────│ User PDS nodes │
18└─────────────┘ └──────┬───────┘ └─────────────────┘
19 │
20 ┌──────▼───────┐
21 │ Forum DID │
22 │ (Service │
23 │ Account) │
24 └──────────────┘
25```
26
27User-generated content (posts, reactions, memberships) lives on each user's PDS. Forum metadata (categories, roles, mod actions) lives on a dedicated Forum Service Account. The AppView indexes both into a unified view.
28
29## Packages
30
31This is a [Turborepo](https://turbo.build/) monorepo with [pnpm](https://pnpm.io/) workspaces.
32
33| Package | Description |
34|---------|-------------|
35| [`packages/lexicon`](packages/lexicon) | AT Proto lexicon schemas (YAML) and generated TypeScript types |
36| [`packages/appview`](packages/appview) | Hono-based JSON API server |
37| [`packages/web`](packages/web) | Server-rendered web UI (Hono JSX + HTMX) |
38| [`packages/spike`](packages/spike) | PDS read/write test script |
39
40## Getting Started
41
42### Prerequisites
43
44- [Nix](https://nixos.org/) with [devenv](https://devenv.sh/) installed
45
46### Setup
47
48```sh
49# Enter the development shell (provides Node.js, pnpm, turbo)
50devenv shell
51
52# Install dependencies
53pnpm install
54
55# Copy and configure environment variables
56cp .env.example .env
57# Edit .env with your Forum Service Account credentials
58
59# Build all packages
60pnpm build
61```
62
63### Development
64
65```sh
66# Start both servers with hot reload
67devenv up
68
69# Or start individually
70pnpm --filter @atbb/appview dev # API server on http://localhost:3000
71pnpm --filter @atbb/web dev # Web UI on http://localhost:3001
72```
73
74### Other Commands
75
76```sh
77pnpm build # Build all packages
78pnpm clean # Remove all build artifacts
79pnpm lint # Type-check all packages
80```
81
82## Lexicons
83
84atBB defines custom AT Proto record types under the `space.atbb.*` namespace:
85
86| Lexicon | Owner | Description |
87|---------|-------|-------------|
88| `space.atbb.forum.forum` | Forum DID | Forum metadata (name, description) |
89| `space.atbb.forum.category` | Forum DID | Subforum / category definitions |
90| `space.atbb.forum.role` | Forum DID | Role definitions with permission tokens |
91| `space.atbb.post` | User DID | Posts and replies (unified model) |
92| `space.atbb.membership` | User DID | User's membership in a forum |
93| `space.atbb.reaction` | User DID | Reactions on posts (like, upvote, etc.) |
94| `space.atbb.modAction` | Forum DID | Moderation actions (ban, lock, pin, etc.) |
95
96Lexicon source files are YAML in `packages/lexicon/lexicons/`. The build pipeline converts them to JSON and generates TypeScript types via `@atproto/lex-cli`.
97
98## Project Status
99
100See [`docs/atproto-forum-plan.md`](docs/atproto-forum-plan.md) for the full project plan and current progress.
101
102**Current phase:** Phase 0 (Foundation) — complete. Monorepo scaffolding, lexicon definitions, and package stubs are in place. Phase 1 (AppView Core) is next.
103
104## Prior Art
105
106The `prior-art/` directory contains git submodules referencing earlier implementations:
107
108- **[atBB](https://github.com/atBB-Community/atBB)** — Original Rust AppView (Axum + SQLx)
109- **[lexicon](https://github.com/atBB-Community/lexicon)** — Original lexicon definitions
110- **[at-delegation](https://github.com/atBB-Community/at-delegation)** — AT Protocol privilege delegation spec (post-MVP)
111
112## License
113
114[AGPL-3.0](LICENSE)