# atBB

**A BB-style forum, on the ATmosphere!**

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.

- **Domain:** [atbb.space](https://atbb.space)
- **Lexicon namespace:** `space.atbb.*`
- **License:** AGPL-3.0
- **Organization:** [atBB-Community](https://github.com/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](https://turbo.build/) monorepo with [pnpm](https://pnpm.io/) workspaces.

### Apps (`apps/`)

| App | Description |
|-----|-------------|
| [`apps/appview`](apps/appview) | Hono-based JSON API server |
| [`apps/web`](apps/web) | Server-rendered web UI (Hono JSX + HTMX) |

### Packages (`packages/`)

| Package | Description |
|---------|-------------|
| [`packages/atproto`](packages/atproto) | AT Protocol utilities: ForumAgent, error classification, identity resolution |
| [`packages/cli`](packages/cli) | Forum management CLI (`atbb`) for initializing forums, categories, and boards |
| [`packages/db`](packages/db) | Drizzle ORM schema and connection factory (PostgreSQL and SQLite/LibSQL) |
| [`packages/lexicon`](packages/lexicon) | AT Proto lexicon schemas (YAML) and generated TypeScript types |
| [`packages/logger`](packages/logger) | Structured logging with OpenTelemetry and Hono middleware support |

## Getting Started

### Prerequisites

- [Nix](https://nixos.org/) with [devenv](https://devenv.sh/) installed

### Setup

```sh
# 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

```sh
# 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

```sh
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

```sh
# 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`](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`.

## License

[AGPL-3.0](LICENSE)