gui.do
Barazo AppView backend
barazo.forum
docs: replace CLAUDE.md with AGENTS.md
AGENTS.md is the cross-vendor standard for AI coding agent instructions.
Auto-generated from barazo-workspace/agents-md/ source files.
+77
AGENTS.md
+77
AGENTS.md
···
1
+
# Barazo API -- AppView Backend
2
+
3
+
<!-- Auto-generated from barazo-workspace. To propose changes, edit the source:
4
+
https://github.com/barazo-forum/barazo-workspace/tree/main/agents-md -->
5
+
6
+
AGPL-3.0 | Part of [github.com/barazo-forum](https://github.com/barazo-forum)
7
+
8
+
The AppView backend for Barazo. Subscribes to AT Protocol firehose, indexes `forum.barazo.*` records in PostgreSQL, and exposes a REST API for all forum operations.
9
+
10
+
## Tech Stack
11
+
12
+
| Component | Technology |
13
+
|-----------|-----------|
14
+
| Runtime | Node.js 24 LTS / TypeScript (strict) |
15
+
| Framework | Fastify |
16
+
| Protocol | @atproto/api, @atproto/oauth-client-node, @atproto/tap |
17
+
| Database | PostgreSQL 16 (Drizzle ORM, Drizzle Kit migrations) |
18
+
| Cache | Valkey |
19
+
| Testing | Vitest + Supertest |
20
+
| Logging | Pino (structured) |
21
+
| Monitoring | GlitchTip (Sentry SDK-compatible) |
22
+
| Security | Helmet + Zod + DOMPurify + rate limiting |
23
+
24
+
## What This Repo Does
25
+
26
+
- Subscribes to the AT Protocol firehose via Tap, filtering for `forum.barazo.*` collections
27
+
- Indexes forum records (topics, replies, categories, reactions) in PostgreSQL
28
+
- Exposes REST API routes: `/api/forum/*`, `/api/admin/*`
29
+
- Runs in two modes: single-forum (one community) or global (all Barazo forums)
30
+
- Handles AT Protocol OAuth authentication
31
+
- Validates all firehose records before indexing (Zod)
32
+
- Validates all API input (Zod), sanitizes all output (DOMPurify)
33
+
34
+
## API-Specific Standards
35
+
36
+
- Every API endpoint validates input with a Zod schema
37
+
- Every firehose record validated before indexing
38
+
- DOMPurify sanitization on all user-generated content output
39
+
- Helmet + CSP + HSTS + rate limiting on all endpoints
40
+
- GlitchTip error monitoring from first deployment
41
+
- No raw SQL -- Drizzle ORM with parameterized queries only
42
+
43
+
---
44
+
45
+
## Project-Wide Standards
46
+
47
+
### About Barazo
48
+
49
+
Federated forum built on the [AT Protocol](https://atproto.com/). Portable identity, user-owned data, cross-community reputation.
50
+
51
+
- **Organization:** [github.com/barazo-forum](https://github.com/barazo-forum)
52
+
- **License:** AGPL-3.0 (backend) / MIT (frontend, lexicons, deploy, website)
53
+
- **Contributing:** See [CONTRIBUTING.md](https://github.com/barazo-forum/.github/blob/main/CONTRIBUTING.md)
54
+
55
+
### Coding Standards
56
+
57
+
1. **Test-Driven Development** -- write tests before implementation (Vitest).
58
+
2. **Strict TypeScript** -- `strict: true`, no `any`, no `@ts-ignore`.
59
+
3. **Conventional commits** -- `type(scope): description`.
60
+
4. **CI must pass** -- lint, typecheck, tests, security scan on every PR.
61
+
5. **Input validation** -- Zod schemas on all API inputs and firehose records.
62
+
6. **Output sanitization** -- DOMPurify on all user-generated content.
63
+
7. **No raw SQL** -- Drizzle ORM with parameterized queries only.
64
+
8. **Structured logging** -- Pino logger, never `console.log`.
65
+
9. **Accessibility** -- WCAG 2.2 AA, semantic HTML, keyboard navigable.
66
+
67
+
### Git Workflow
68
+
69
+
All changes go through Pull Requests -- never commit directly to `main`. Branch naming: `type/short-description` (e.g., `feat/add-reactions`, `fix/xss-sanitization`).
70
+
71
+
### AT Protocol Context
72
+
73
+
- Users own their data (stored on their Personal Data Server)
74
+
- The AppView (barazo-api) indexes data from the AT Protocol firehose
75
+
- Lexicons (`forum.barazo.*`) define the data schema contract
76
+
- Identity is portable via DIDs -- no vendor lock-in
77
+
- All record types are validated against lexicon schemas