diff --git a/.gitignore b/.gitignore index 1bc9309..60a53b0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ # Claude Code -CLAUDE.md .claude/ # Git worktrees diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d084443 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,77 @@ +# Barazo API -- AppView Backend + + + +AGPL-3.0 | Part of [github.com/barazo-forum](https://github.com/barazo-forum) + +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. + +## Tech Stack + +| Component | Technology | +|-----------|-----------| +| Runtime | Node.js 24 LTS / TypeScript (strict) | +| Framework | Fastify | +| Protocol | @atproto/api, @atproto/oauth-client-node, @atproto/tap | +| Database | PostgreSQL 16 (Drizzle ORM, Drizzle Kit migrations) | +| Cache | Valkey | +| Testing | Vitest + Supertest | +| Logging | Pino (structured) | +| Monitoring | GlitchTip (Sentry SDK-compatible) | +| Security | Helmet + Zod + DOMPurify + rate limiting | + +## What This Repo Does + +- Subscribes to the AT Protocol firehose via Tap, filtering for `forum.barazo.*` collections +- Indexes forum records (topics, replies, categories, reactions) in PostgreSQL +- Exposes REST API routes: `/api/forum/*`, `/api/admin/*` +- Runs in two modes: single-forum (one community) or global (all Barazo forums) +- Handles AT Protocol OAuth authentication +- Validates all firehose records before indexing (Zod) +- Validates all API input (Zod), sanitizes all output (DOMPurify) + +## API-Specific Standards + +- Every API endpoint validates input with a Zod schema +- Every firehose record validated before indexing +- DOMPurify sanitization on all user-generated content output +- Helmet + CSP + HSTS + rate limiting on all endpoints +- GlitchTip error monitoring from first deployment +- No raw SQL -- Drizzle ORM with parameterized queries only + +--- + +## Project-Wide Standards + +### About Barazo + +Federated forum built on the [AT Protocol](https://atproto.com/). Portable identity, user-owned data, cross-community reputation. + +- **Organization:** [github.com/barazo-forum](https://github.com/barazo-forum) +- **License:** AGPL-3.0 (backend) / MIT (frontend, lexicons, deploy, website) +- **Contributing:** See [CONTRIBUTING.md](https://github.com/barazo-forum/.github/blob/main/CONTRIBUTING.md) + +### Coding Standards + +1. **Test-Driven Development** -- write tests before implementation (Vitest). +2. **Strict TypeScript** -- `strict: true`, no `any`, no `@ts-ignore`. +3. **Conventional commits** -- `type(scope): description`. +4. **CI must pass** -- lint, typecheck, tests, security scan on every PR. +5. **Input validation** -- Zod schemas on all API inputs and firehose records. +6. **Output sanitization** -- DOMPurify on all user-generated content. +7. **No raw SQL** -- Drizzle ORM with parameterized queries only. +8. **Structured logging** -- Pino logger, never `console.log`. +9. **Accessibility** -- WCAG 2.2 AA, semantic HTML, keyboard navigable. + +### Git Workflow + +All changes go through Pull Requests -- never commit directly to `main`. Branch naming: `type/short-description` (e.g., `feat/add-reactions`, `fix/xss-sanitization`). + +### AT Protocol Context + +- Users own their data (stored on their Personal Data Server) +- The AppView (barazo-api) indexes data from the AT Protocol firehose +- Lexicons (`forum.barazo.*`) define the data schema contract +- Identity is portable via DIDs -- no vendor lock-in +- All record types are validated against lexicon schemas