# 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.

## Packages

This is a [Turborepo](https://turbo.build/) monorepo with [pnpm](https://pnpm.io/) workspaces.

| Package | Description |
|---------|-------------|
| [`packages/lexicon`](packages/lexicon) | AT Proto lexicon schemas (YAML) and generated TypeScript types |
| [`packages/appview`](packages/appview) | Hono-based JSON API server |
| [`packages/web`](packages/web) | Server-rendered web UI (Hono JSX + HTMX) |
| [`packages/spike`](packages/spike) | PDS read/write test script |

## 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 clean          # Remove all build artifacts
pnpm lint           # Type-check all packages
```

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

## Project Status

See [`docs/atproto-forum-plan.md`](docs/atproto-forum-plan.md) for the full project plan and current progress.

**Current phase:** Phase 0 (Foundation) — complete. Monorepo scaffolding, lexicon definitions, and package stubs are in place. Phase 1 (AppView Core) is next.

## Prior Art

The `prior-art/` directory contains git submodules referencing earlier implementations:

- **[atBB](https://github.com/atBB-Community/atBB)** — Original Rust AppView (Axum + SQLx)
- **[lexicon](https://github.com/atBB-Community/lexicon)** — Original lexicon definitions
- **[at-delegation](https://github.com/atBB-Community/at-delegation)** — AT Protocol privilege delegation spec (post-MVP)

## License

[AGPL-3.0](LICENSE)