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
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## Apps & Packages
30
31This is a [Turborepo](https://turbo.build/) monorepo with [pnpm](https://pnpm.io/) workspaces.
32
33### Apps (`apps/`)
34
35| App | Description |
36|-----|-------------|
37| [`apps/appview`](apps/appview) | Hono-based JSON API server |
38| [`apps/web`](apps/web) | Server-rendered web UI (Hono JSX + HTMX) |
39
40### Packages (`packages/`)
41
42| Package | Description |
43|---------|-------------|
44| [`packages/atproto`](packages/atproto) | AT Protocol utilities: ForumAgent, error classification, identity resolution |
45| [`packages/cli`](packages/cli) | Forum management CLI (`atbb`) for initializing forums, categories, and boards |
46| [`packages/db`](packages/db) | Drizzle ORM schema and connection factory (PostgreSQL and SQLite/LibSQL) |
47| [`packages/lexicon`](packages/lexicon) | AT Proto lexicon schemas (YAML) and generated TypeScript types |
48| [`packages/logger`](packages/logger) | Structured logging with OpenTelemetry and Hono middleware support |
49
50## Getting Started
51
52### Prerequisites
53
54- [Nix](https://nixos.org/) with [devenv](https://devenv.sh/) installed
55
56### Setup
57
58```sh
59# Enter the development shell (provides Node.js, pnpm, turbo)
60devenv shell
61
62# Install dependencies
63pnpm install
64
65# Copy and configure environment variables
66cp .env.example .env
67# Edit .env with your Forum Service Account credentials
68
69# Build all packages
70pnpm build
71```
72
73### Development
74
75```sh
76# Start both servers with hot reload
77devenv up
78
79# Or start individually
80pnpm --filter @atbb/appview dev # API server on http://localhost:3000
81pnpm --filter @atbb/web dev # Web UI on http://localhost:3001
82```
83
84### Other Commands
85
86```sh
87pnpm build # Build all packages
88pnpm test # Run all tests
89pnpm clean # Remove all build artifacts
90pnpm lint # Type-check all packages
91pnpm --filter @atbb/appview db:migrate # Run database migrations
92```
93
94## Deployment
95
96The project includes production-ready Docker infrastructure for containerized deployment.
97
98### Quick Start with Docker
99
100```sh
101# Copy and configure environment variables
102cp .env.example .env
103# Edit .env with production values (DATABASE_URL, FORUM_DID, OAUTH_PUBLIC_URL, etc.)
104
105# Copy and configure docker-compose
106cp docker-compose.example.yml docker-compose.yml
107# Edit docker-compose.yml if needed
108
109# Start services
110docker compose up -d
111
112# Run database migrations
113docker compose exec atbb pnpm --filter @atbb/appview db:migrate
114```
115
116### What's Included
117
118- Multi-stage Dockerfile (Node 22 Alpine, ~200MB final image)
119- Nginx reverse proxy (serves both AppView and Web UI on port 80)
120- Health checks on `/api/healthz`
121- GitHub Actions CI/CD (automated testing and Docker image publishing)
122
123See [`docs/deployment-guide.md`](docs/deployment-guide.md) for comprehensive deployment instructions.
124
125## Lexicons
126
127atBB defines custom AT Proto record types under the `space.atbb.*` namespace:
128
129| Lexicon | Owner | Description |
130|---------|-------|-------------|
131| `space.atbb.forum.forum` | Forum DID | Forum metadata (name, description) |
132| `space.atbb.forum.category` | Forum DID | Subforum / category definitions |
133| `space.atbb.forum.role` | Forum DID | Role definitions with permission tokens |
134| `space.atbb.forum.board` | Forum DID | Board definitions within a category |
135| `space.atbb.post` | User DID | Posts and replies (unified model) |
136| `space.atbb.membership` | User DID | User's membership in a forum |
137| `space.atbb.reaction` | User DID | Reactions on posts (like, upvote, etc.) |
138| `space.atbb.modAction` | Forum DID | Moderation actions (ban, lock, pin, etc.) |
139
140Lexicon source files are YAML in `packages/lexicon/lexicons/`. The build pipeline converts them to JSON and generates TypeScript types via `@atproto/lex-cli`.
141
142## License
143
144[AGPL-3.0](LICENSE)
145