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