malpercio.dev
atBB#
A BB-style forum, on the ATmosphere!
atBB is a decentralized forum built on the AT Protocol. 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.
- Domain: atbb.space
- Lexicon namespace:
space.atbb.* - License: AGPL-3.0
- Organization: atBB-Community
Architecture#
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Forum UI │────▶│ AppView │────▶│ Firehose / │
│ (Web App) │◀────│ (Node/TS) │◀────│ User PDS nodes │
└─────────────┘ └──────┬───────┘ └─────────────────┘
│
┌──────▼───────┐
│ Forum DID │
│ (Service │
│ Account) │
└──────────────┘
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.
Apps & Packages#
This is a Turborepo monorepo with pnpm workspaces.
Apps (apps/)#
| App | Description |
|---|---|
apps/appview |
Hono-based JSON API server |
apps/web |
Server-rendered web UI (Hono JSX + HTMX) |
Packages (packages/)#
| Package | Description |
|---|---|
packages/db |
Drizzle ORM schema and connection factory (PostgreSQL and SQLite/LibSQL) |
packages/lexicon |
AT Proto lexicon schemas (YAML) and generated TypeScript types |
Getting Started#
Prerequisites#
Setup#
# Enter the development shell (provides Node.js, pnpm, turbo)
devenv shell
# Install dependencies
pnpm install
# Copy and configure environment variables
cp .env.example .env
# Edit .env with your Forum Service Account credentials
# Build all packages
pnpm build
Development#
# Start both servers with hot reload
devenv up
# Or start individually
pnpm --filter @atbb/appview dev # API server on http://localhost:3000
pnpm --filter @atbb/web dev # Web UI on http://localhost:3001
Other Commands#
pnpm build # Build all packages
pnpm test # Run all tests
pnpm clean # Remove all build artifacts
pnpm lint # Type-check all packages
pnpm --filter @atbb/appview db:migrate # Run database migrations
Deployment#
The project includes production-ready Docker infrastructure for containerized deployment.
Quick Start with Docker#
# Copy and configure environment variables
cp .env.example .env
# Edit .env with production values (DATABASE_URL, FORUM_DID, OAUTH_PUBLIC_URL, etc.)
# Copy and configure docker-compose
cp docker-compose.example.yml docker-compose.yml
# Edit docker-compose.yml if needed
# Start services
docker compose up -d
# Run database migrations
docker compose exec atbb pnpm --filter @atbb/appview db:migrate
What's Included#
- Multi-stage Dockerfile (Node 22 Alpine, ~200MB final image)
- Nginx reverse proxy (serves both AppView and Web UI on port 80)
- Health checks on
/api/healthz - GitHub Actions CI/CD (automated testing and Docker image publishing)
See docs/deployment-guide.md for comprehensive deployment instructions.
Lexicons#
atBB defines custom AT Proto record types under the space.atbb.* namespace:
| Lexicon | Owner | Description |
|---|---|---|
space.atbb.forum.forum |
Forum DID | Forum metadata (name, description) |
space.atbb.forum.category |
Forum DID | Subforum / category definitions |
space.atbb.forum.role |
Forum DID | Role definitions with permission tokens |
space.atbb.forum.board |
Forum DID | Board definitions within a category |
space.atbb.post |
User DID | Posts and replies (unified model) |
space.atbb.membership |
User DID | User's membership in a forum |
space.atbb.reaction |
User DID | Reactions on posts (like, upvote, etc.) |
space.atbb.modAction |
Forum DID | Moderation actions (ban, lock, pin, etc.) |
Lexicon source files are YAML in packages/lexicon/lexicons/. The build pipeline converts them to JSON and generates TypeScript types via @atproto/lex-cli.