gui.do
Barazo AppView backend
barazo.forum
1# Barazo API -- AppView Backend
2
3<!-- Auto-generated from barazo-workspace. To propose changes, edit the source:
4 https://github.com/singi-labs/barazo-workspace/tree/main/agents-md -->
5
6AGPL-3.0 | Part of [github.com/singi-labs](https://github.com/singi-labs)
7
8The 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 push) |
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- Accessible error responses -- include human-readable messages and structured error codes to support accessible frontend rendering
43
44---
45
46## Project-Wide Standards
47
48### About Barazo
49
50Open-source forum software built on the [AT Protocol](https://atproto.com/). Portable identity, member-owned data, no lock-in.
51
52- **Organization:** [github.com/singi-labs](https://github.com/singi-labs)
53- **License:** AGPL-3.0 (backend) / MIT (frontend, lexicons, deploy) / CC BY-SA 4.0 + MIT (docs) / Proprietary (website)
54- **Contributing:** See [CONTRIBUTING.md](https://github.com/singi-labs/.github/blob/main/CONTRIBUTING.md)
55
56### Coding Standards
57
581. **Test-Driven Development** -- write tests before implementation (Vitest).
592. **Strict TypeScript** -- `strict: true`, no `any`, no `@ts-ignore`.
603. **Conventional commits** -- `type(scope): description`.
614. **CI must pass** -- lint, typecheck, tests, security scan on every PR.
625. **Input validation** -- Zod schemas on all API inputs and firehose records.
636. **Output sanitization** -- DOMPurify on all user-generated content.
647. **No raw SQL** -- Drizzle ORM with parameterized queries only.
658. **Structured logging** -- Pino logger, never `console.log`.
66
67### Git Workflow
68
69All 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