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
docs: remove a few things from claude.md that can be discovered in project
+3
-172
CLAUDE.md
+3
-172
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
-
## Apps & Packages
8
-
9
-
### Apps (`apps/`)
10
-
11
-
Servers and applications that are deployed or run as services.
12
-
13
-
| App | Description | Port |
14
-
|-----|-------------|------|
15
-
| `@atbb/appview` | Hono JSON API server — indexes forum data, serves API | 3000 |
16
-
| `@atbb/web` | Hono JSX + HTMX server-rendered web UI — calls appview API | 3001 |
1
+
# Claude.md
17
2
18
-
### Packages (`packages/`)
19
-
20
-
Shared libraries, tools, and utilities consumed by apps or used standalone.
21
-
22
-
| Package | Description |
23
-
|---------|-------------|
24
-
| `@atbb/db` | Drizzle ORM schema and connection factory for PostgreSQL |
25
-
| `@atbb/lexicon` | AT Proto lexicon definitions (YAML) + generated TypeScript types |
3
+
The role of this file is to describe common mistakes and confusion points that agents might encounter as they work in this project. If you ever encounter something in the project that surprises you, please alert the developer working with you and indicate that this is the case in the Claude.md file to help prevent future agents from having the same issue.
26
4
27
-
**Dependency chain:** `@atbb/lexicon` and `@atbb/db` build first, then `@atbb/appview` and `@atbb/web` build in parallel. Turbo handles this via `^build`.
5
+
This project is greenfield. It is okay to change the schema entirely or make what might be breaking changes. We will sort out any backfill or backwards compatibility requirements when they are actually needed.
28
6
29
7
## Development
30
8
···
36
14
cp .env.example .env # configure environment variables
37
15
```
38
16
39
-
### Commands
40
-
41
-
```sh
42
-
pnpm build # build all packages (lexicon → appview + web)
43
-
pnpm dev # start all dev servers with hot reload
44
-
pnpm test # run all tests across all packages
45
-
pnpm clean # remove all dist/ directories
46
-
devenv up # start appview + web servers via process manager
47
-
pnpm --filter @atbb/appview db:migrate # run database migrations
48
-
pnpm --filter @atbb/appview dev # run a single package
49
-
pnpm --filter @atbb/appview test # run tests for a single package
50
-
```
51
-
52
-
### Environment Variables
53
-
54
-
See `.env.example`. Key variables:
55
-
56
-
- `PORT` — server port (appview: 3000, web: 3001)
57
-
- `FORUM_DID` — the forum's AT Proto DID
58
-
- `PDS_URL` — URL of the forum's PDS
59
-
- `APPVIEW_URL` — URL the web package uses to reach the appview API
60
-
- `FORUM_HANDLE`, `FORUM_PASSWORD` — forum service account credentials
61
-
62
-
**OAuth & session management (required for production):**
63
-
- `OAUTH_PUBLIC_URL` — public URL where AppView is accessible (used for client_id and redirect_uri)
64
-
- `SESSION_SECRET` — signing key for session tokens (generate with `openssl rand -hex 32`)
65
-
- `SESSION_TTL_DAYS` — session lifetime in days (default: 7)
66
-
- `REDIS_URL` — optional Redis URL for session storage (recommended for multi-instance deployments)
67
-
68
-
## Deployment
69
-
70
-
### Docker
71
-
72
-
The project includes production-ready Docker infrastructure for single-container deployment:
73
-
74
-
```sh
75
-
# Build the Docker image
76
-
docker build -t atbb:latest .
77
-
78
-
# Run with docker-compose (recommended)
79
-
cp docker-compose.example.yml docker-compose.yml
80
-
# Edit docker-compose.yml with your DATABASE_URL, FORUM_DID, etc.
81
-
docker compose up -d
82
-
```
83
-
84
-
**What's included:**
85
-
- Multi-stage Dockerfile (Node 22 Alpine, ~200MB final image)
86
-
- Nginx reverse proxy serving both appview (port 3000) and web (port 3001) on port 80
87
-
- Non-root user (`atbb:atbb`) for security
88
-
- Health checks on `/api/healthz`
89
-
- Production-ready entrypoint script
90
-
91
-
**Key files:**
92
-
- `Dockerfile` — multi-stage build definition
93
-
- `entrypoint.sh` — startup script (nginx + node servers)
94
-
- `nginx.conf` — reverse proxy configuration
95
-
- `docker-compose.example.yml` — orchestration template
96
-
- `docs/deployment-guide.md` — comprehensive deployment instructions
97
-
98
-
**Database migrations:** The container does NOT auto-run migrations. Run manually before starting:
99
-
```sh
100
-
docker compose run --rm atbb pnpm --filter @atbb/appview db:migrate
101
-
```
102
-
103
-
## Pre-Commit Checks
104
-
105
-
Every commit automatically runs three checks in parallel via lefthook:
106
-
107
-
1. **Lint** — oxlint scans staged TypeScript/JavaScript files for code quality issues
108
-
2. **Typecheck** — `pnpm turbo lint` runs type checking on affected packages
109
-
3. **Test** — Vitest runs tests in packages with staged changes
110
-
111
17
### Auto-Fixing Lint Issues
112
18
113
19
Before committing, auto-fix safe lint violations:
···
120
26
pnpm --filter @atbb/appview lint:fix
121
27
```
122
28
123
-
### Bypassing Hooks (Emergency Only)
124
-
125
-
In urgent situations, bypass hooks with:
126
-
127
-
```sh
128
-
git commit --no-verify -m "emergency: your message"
129
-
```
130
-
131
-
Use sparingly — hooks catch issues that would fail in CI.
132
-
133
-
## CI/CD
134
-
135
-
### GitHub Actions Workflows
136
-
137
-
**`.github/workflows/ci.yml`** — Runs on all pull requests (parallel jobs):
138
-
- **Lint:** `pnpm exec oxlint .` — catches code quality issues
139
-
- **Type Check:** `pnpm turbo lint` — verifies TypeScript types across all packages
140
-
- **Test:** `pnpm test` — runs all tests with PostgreSQL 17 service container
141
-
- **Build:** `pnpm build` — verifies compilation succeeds
142
-
143
-
**`.github/workflows/publish.yml`** — Runs on pushes to `main` branch:
144
-
- Builds Docker image and publishes to GitHub Container Registry (GHCR)
145
-
- Tags: `latest` (main branch) and `sha-<commit>` (specific commit)
146
-
- Image: `ghcr.io/atbb-community/atbb:latest`
147
-
148
-
**All checks must pass before merging a PR.**
149
-
150
-
### How Hooks Work
151
-
152
-
- **Lefthook** manages git hooks (`lefthook.yml`)
153
-
- **Oxlint** provides fast linting (`.oxlintrc.json`)
154
-
- **Turbo** filters checks to affected packages only
155
-
- Hooks auto-install after `pnpm install` via `prepare` script
156
-
157
29
## Testing Standards
158
30
159
31
**CRITICAL: Always run tests before committing code or requesting code review.**
160
-
161
-
### Running Tests
162
-
163
-
```sh
164
-
# Run all tests
165
-
pnpm test
166
-
167
-
# Run tests for a specific package
168
-
pnpm --filter @atbb/appview test
169
-
170
-
# Run tests in watch mode during development
171
-
pnpm --filter @atbb/appview test --watch
172
-
173
-
# Run a specific test file
174
-
pnpm --filter @atbb/appview test src/lib/__tests__/config.test.ts
175
-
```
176
32
177
33
### Environment Variables in Tests
178
34
···
277
133
278
134
**If you're unsure how to test something:** Leave a `// TODO: Add test for X` comment and create a Linear issue. Never commit a stub test that pretends to test something.
279
135
280
-
### Example Test Structure
281
-
282
-
```typescript
283
-
describe("createForumRoutes", () => {
284
-
it("returns forum metadata when forum exists", async () => {
285
-
// Arrange: Set up test context with mock data
286
-
const ctx = await createTestContext();
287
-
288
-
// Act: Call the endpoint
289
-
const res = await app.request("/api/forum");
290
-
291
-
// Assert: Verify response
292
-
expect(res.status).toBe(200);
293
-
const data = await res.json();
294
-
expect(data.name).toBe("Test Forum");
295
-
});
296
-
297
-
it("returns 404 when forum does not exist", async () => {
298
-
// Test error case
299
-
const ctx = await createTestContext({ emptyDb: true });
300
-
const res = await app.request("/api/forum");
301
-
expect(res.status).toBe(404);
302
-
});
303
-
});
304
-
```
305
136
306
137
### Test Coverage Expectations
307
138