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
Add CLAUDE.md with project context for future agents
Documents architecture, dev setup, lexicon conventions, AT Protocol
patterns, TypeScript/Hono gotchas, and git conventions.
+78
CLAUDE.md
+78
CLAUDE.md
···
1
+
# atBB Monorepo
2
+
3
+
**atBB** is a decentralized BB-style forum built on the AT Protocol. Users own their posts on their own PDS; the forum's AppView indexes and serves them. Lexicon namespace: `space.atbb.*` (domain `atbb.space` is owned). License: AGPL-3.0.
4
+
5
+
The master project plan with MVP phases and progress tracking lives at `docs/atproto-forum-plan.md`.
6
+
7
+
## Packages
8
+
9
+
| Package | Description | Port |
10
+
|---------|-------------|------|
11
+
| `@atbb/lexicon` | AT Proto lexicon definitions (YAML) + generated TypeScript types | — |
12
+
| `@atbb/appview` | Hono JSON API server — indexes forum data, serves API | 3000 |
13
+
| `@atbb/web` | Hono JSX + HTMX server-rendered web UI — calls appview API | 3001 |
14
+
| `@atbb/spike` | PDS read/write test script for validating AT Proto operations | — |
15
+
16
+
**Dependency chain:** `@atbb/lexicon` builds first (generates types), then `@atbb/appview` and `@atbb/web` build in parallel. Turbo handles this via `^build`.
17
+
18
+
## Development
19
+
20
+
### Setup
21
+
22
+
```sh
23
+
devenv shell # enter Nix dev shell (Node.js, pnpm, turbo)
24
+
pnpm install # install all workspace dependencies
25
+
cp .env.example .env # configure environment variables
26
+
```
27
+
28
+
### Commands
29
+
30
+
```sh
31
+
pnpm build # build all packages (lexicon → appview + web)
32
+
pnpm dev # start all dev servers with hot reload
33
+
pnpm clean # remove all dist/ directories
34
+
devenv up # start appview + web servers via process manager
35
+
pnpm --filter @atbb/appview dev # run a single package
36
+
pnpm --filter @atbb/spike spike # run the PDS spike script
37
+
```
38
+
39
+
### Environment Variables
40
+
41
+
See `.env.example`. Key variables:
42
+
43
+
- `PORT` — server port (appview: 3000, web: 3001)
44
+
- `FORUM_DID` — the forum's AT Proto DID
45
+
- `PDS_URL` — URL of the forum's PDS
46
+
- `APPVIEW_URL` — URL the web package uses to reach the appview API
47
+
- `FORUM_HANDLE`, `FORUM_PASSWORD` — forum service account credentials (for spike/writes)
48
+
49
+
## Lexicon Conventions
50
+
51
+
- **Source of truth is YAML** in `packages/lexicon/lexicons/`. Never edit generated JSON or TypeScript.
52
+
- **Build pipeline:** YAML → JSON (`scripts/build.ts`) → TypeScript (`@atproto/lex-cli gen-api`).
53
+
- **Adding a new lexicon:** Create a `.yaml` file under `lexicons/space/atbb/`, run `pnpm --filter @atbb/lexicon build`.
54
+
- **Record keys:** Use `key: tid` for collections (multiple records per repo). Use `key: literal:self` for singletons.
55
+
- **References:** Use `com.atproto.repo.strongRef` wrapped in named defs (e.g., `forumRef`, `subjectRef`).
56
+
- **Extensible fields:** Use `knownValues` (not `enum`) for strings that may grow (permissions, reaction types, mod actions).
57
+
- **Record ownership:**
58
+
- Forum DID owns: `forum.forum`, `forum.category`, `forum.role`, `modAction`
59
+
- User DID owns: `post`, `membership`, `reaction`
60
+
61
+
## AT Protocol Conventions
62
+
63
+
- **Unified post model:** There is no separate "topic" type. A `space.atbb.post` without a `reply` ref is a topic starter; one with a `reply` ref is a reply.
64
+
- **Reply chains:** `replyRef` has both `root` (thread starter) and `parent` (direct parent) — same pattern as `app.bsky.feed.post`.
65
+
- **MVP trust model:** The AppView holds the Forum DID's signing keys directly and writes forum-level records on behalf of admins/mods after verifying their role. This will be replaced by AT Protocol privilege delegation post-MVP.
66
+
67
+
## TypeScript / Hono Gotchas
68
+
69
+
- **`@types/node` is required** as a devDependency in every package that uses `process.env` or other Node APIs. `tsx` doesn't need it at runtime, but `tsc` builds will fail without it.
70
+
- **Hono JSX `children`:** Use `PropsWithChildren<T>` from `hono/jsx` for components that accept children. Unlike React, Hono's `FC<T>` does not include `children` implicitly.
71
+
- **HTMX attributes in JSX:** The `typed-htmx` package provides types for `hx-*` attributes. See `packages/web/src/global.d.ts` for the augmentation.
72
+
- **Glob expansion in npm scripts:** `@atproto/lex-cli` needs file paths, not globs. Use `bash -c 'shopt -s globstar && ...'` to expand `**/*.json` in npm scripts.
73
+
74
+
## Git Conventions
75
+
76
+
- Do not include `Co-Authored-By` lines in commit messages.
77
+
- `prior-art/` contains git submodules (Rust AppView, original lexicons, delegation spec) — reference material only, not used at build time.
78
+
- Worktrees with submodules need `submodule deinit --all -f` then `worktree remove --force` to clean up.