malpercio.dev
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
Add README with project overview, setup guide, and lexicon reference
+114
README.md
+114
README.md
···
1
+
# atBB
2
+
3
+
**A BB-style forum, on the ATmosphere!**
4
+
5
+
atBB 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
+
27
+
User-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
+
31
+
This 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)
50
+
devenv shell
51
+
52
+
# Install dependencies
53
+
pnpm install
54
+
55
+
# Copy and configure environment variables
56
+
cp .env.example .env
57
+
# Edit .env with your Forum Service Account credentials
58
+
59
+
# Build all packages
60
+
pnpm build
61
+
```
62
+
63
+
### Development
64
+
65
+
```sh
66
+
# Start both servers with hot reload
67
+
devenv up
68
+
69
+
# Or start individually
70
+
pnpm --filter @atbb/appview dev # API server on http://localhost:3000
71
+
pnpm --filter @atbb/web dev # Web UI on http://localhost:3001
72
+
```
73
+
74
+
### Other Commands
75
+
76
+
```sh
77
+
pnpm build # Build all packages
78
+
pnpm clean # Remove all build artifacts
79
+
pnpm lint # Type-check all packages
80
+
```
81
+
82
+
## Lexicons
83
+
84
+
atBB 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
+
96
+
Lexicon 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
+
100
+
See [`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
+
106
+
The `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)