gui.do / barazo-api
Barazo AppView backend barazo.forum
fork atom
barazo-api / README.md
at main 269 lines 12 kB view raw view rendered
Guido X Jansen docs: update footer to Singi Labs with EU tagline (#165)
b53a9dc2
1<div align="center"> 2 3<picture> 4 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/singi-labs/.github/main/assets/logo-dark.svg"> 5 <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/singi-labs/.github/main/assets/logo-light.svg"> 6 <img alt="Barazo Logo" src="https://raw.githubusercontent.com/singi-labs/.github/main/assets/logo-dark.svg" width="120"> 7</picture> 8 9# Barazo API 10 11**AT Protocol AppView backend for federated forums -- portable identity, user data ownership, cross-community reputation.** 12 13[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)]() 14[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](https://opensource.org/licenses/AGPL-3.0) 15[![CI](https://github.com/singi-labs/barazo-api/actions/workflows/ci.yml/badge.svg)](https://github.com/singi-labs/barazo-api/actions/workflows/ci.yml) 16[![Node.js](https://img.shields.io/badge/node-24%20LTS-brightgreen)](https://nodejs.org/) 17[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)](https://www.typescriptlang.org/) 18 19</div> 20 21--- 22 23## Overview 24 25The AppView backend for Barazo forums. Handles authentication, forum CRUD, firehose indexing, moderation, search, and cross-posting -- all built on the AT Protocol. Communicates with any compatible frontend via REST API. Runs as a single-community forum or a global aggregator indexing all Barazo communities network-wide. 26 27--- 28 29## Tech Stack 30 31| Component | Technology | 32| ---------- | -------------------------------------------------------------- | 33| Runtime | Node.js 24 LTS / TypeScript (strict mode) | 34| Framework | Fastify 5 | 35| Protocol | @atproto/api, @atproto/oauth-client-node, @atproto/tap | 36| Database | PostgreSQL 16 + pgvector (Drizzle ORM, Drizzle Kit migrations) | 37| Cache | Valkey (via ioredis) | 38| Validation | Zod 4 | 39| Testing | Vitest 4 + Supertest + Testcontainers | 40| Logging | Pino (structured) | 41| Monitoring | GlitchTip (self-hosted, Sentry SDK-compatible) | 42| Security | Helmet + DOMPurify + rate limiting + CSP/HSTS | 43| API docs | @fastify/swagger + Scalar | 44 45--- 46 47## Route Modules 48 4915 route modules across 74 source files: 50 51| Module | File | Functionality | 52| -------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | 53| Auth | `auth.ts` | AT Protocol OAuth sign-in with any PDS | 54| OAuth Metadata | `oauth-metadata.ts` | OAuth discovery metadata endpoint | 55| Health | `health.ts` | Health check | 56| Topics | `topics.ts` | CRUD, sorting (chronological / reactions / trending), cross-posting to Bluesky + Frontpage, self-labels | 57| Replies | `replies.ts` | CRUD threaded replies, self-labels | 58| Categories | `categories.ts` | CRUD with maturity ratings (SFW / Mature / Adult), parent-child hierarchy | 59| Reactions | `reactions.ts` | Configurable reaction types per community | 60| Search | `search.ts` | Full-text search (PostgreSQL tsvector + GIN index), optional semantic search via `EMBEDDING_URL` | 61| Profiles | `profiles.ts` | User profiles with PDS sync, cross-community reputation, age declaration | 62| Notifications | `notifications.ts` | In-app and email notification system | 63| Moderation | `moderation.ts` | Lock, pin, delete, ban, content reporting, first-post queue, word/phrase blocklists, link spam detection, mod action log | 64| Admin Settings | `admin-settings.ts` | Community settings, maturity rating, branding, jurisdiction + age threshold configuration | 65| Block / Mute | `block-mute.ts` | Block and mute users (portable via PDS records) | 66| Onboarding | `onboarding.ts` | Admin-configurable community onboarding fields, user response submission and status tracking | 67| Setup | `setup.ts` | Initial community setup wizard | 68 69--- 70 71## Database Schema 72 7315 schema modules (Drizzle ORM): 74 75| Schema | Purpose | 76| ----------------------- | -------------------------------------------------------- | 77| `users.ts` | User accounts synced from PDS | 78| `topics.ts` | Forum topics with maturity, self-labels | 79| `replies.ts` | Threaded replies | 80| `categories.ts` | Category hierarchy with maturity ratings | 81| `reactions.ts` | Reaction records | 82| `reports.ts` | Content reports | 83| `notifications.ts` | Notification records | 84| `moderation-actions.ts` | Moderation action log | 85| `cross-posts.ts` | Bluesky + Frontpage cross-post tracking | 86| `community-settings.ts` | Per-community configuration, jurisdiction, age threshold | 87| `user-preferences.ts` | Global and per-community user preferences | 88| `onboarding-fields.ts` | Admin-defined onboarding fields and user responses | 89| `tracked-repos.ts` | AT Protocol repo tracking state | 90| `firehose.ts` | Firehose cursor and subscription state | 91| `index.ts` | Schema barrel export | 92 93--- 94 95## Features 96 97**AT Protocol integration:** 98 99- OAuth authentication with any AT Protocol PDS 100- Firehose subscription via Tap, filtered for `forum.barazo.*` collections 101- Record validation (Zod) before indexing 102- Portable block/mute records stored on user PDS 103- Cross-posting to Bluesky (default on, toggleable per topic) and Frontpage (feature flag) 104- Cross-post deletion lifecycle (topic delete cascades to cross-posts) 105- Rich OpenGraph images for cross-posts (forum branding, topic title, category) 106- Self-labels on topics and replies 107- Two operating modes: single-forum or global aggregator (`COMMUNITY_MODE=global`) 108 109**Forum core:** 110 111- Topics CRUD with sorting (chronological, reactions, trending) 112- Threaded replies CRUD 113- Categories with parent-child hierarchy and per-category maturity ratings 114- Configurable reaction types per community 115- Full-text search (PostgreSQL tsvector + GIN index) 116- Optional semantic search (pgvector, activated by `EMBEDDING_URL`) 117- In-app and email notifications 118- User profiles with PDS sync 119- Cross-community reputation (activity counts across forums) 120- User preferences (global and per-community) 121 122**Content maturity and age gating:** 123 124- Three-tier content maturity system: SFW, Mature, Adult 125- Maturity ratings at both forum and category level 126- Content maturity filtering based on user age declaration 127- Age declaration as numeric value with jurisdiction-aware thresholds 128- Admin-configurable jurisdiction country and age threshold 129 130**Moderation:** 131 132- Content reporting system 133- First-post moderation queue 134- Word and phrase blocklists 135- Link spam detection 136- Topic lock, pin, and delete 137- User bans 138- Moderation action log 139- GDPR-compliant account deletion (identity event handling) 140 141**Community administration:** 142 143- Admin settings panel (name, description, branding, colors) 144- Community setup wizard 145- Admin-configurable onboarding fields (text, select, checkbox, etc.) 146- User onboarding response submission and completion tracking 147- Jurisdiction and age threshold configuration 148 149**Plugin system:** 150 151- Plugin-aware route architecture across all modules 152 153**Security:** 154 155- Zod validation on all API endpoints 156- DOMPurify output sanitization on all user-generated content 157- Helmet security headers (CSP, HSTS) 158- Rate limiting on all endpoints 159- Pino structured logging (no `console.log`) 160- Sentry-compatible error monitoring (GlitchTip) 161 162--- 163 164## Planned Features 165 166- Semantic search activation (pgvector hybrid ranking) -- infrastructure installed, not yet wired 167- AI-assisted moderation (spam and toxicity flagging) 168- Stripe billing integration (P3) 169- Multi-tenant SaaS management endpoints (P3) 170- AT Protocol labeler integration (P4) 171- Migration API endpoints (P5) 172- Private categories (P4) 173- Solved/accepted answer markers (P4) 174 175--- 176 177## API Documentation 178 179When running, interactive API docs are available at: 180 181- **Local:** `http://localhost:3000/docs` 182- **Production:** `https://api.barazo.forum/docs` 183 184OpenAPI spec: `GET /api/openapi.json` 185 186--- 187 188## Quick Start 189 190**Prerequisites:** Node.js 24 LTS, pnpm, Docker + Docker Compose, AT Protocol PDS access (Bluesky or self-hosted). 191 192```bash 193git clone https://github.com/singi-labs/barazo-api.git 194cd barazo-api 195pnpm install 196 197# Start PostgreSQL + Valkey 198docker compose -f docker-compose.dev.yml up -d 199 200# Configure environment 201cp .env.example .env 202# Edit .env with your settings 203 204# Run development server 205pnpm dev 206``` 207 208--- 209 210## Development 211 212```bash 213pnpm test # Run all tests 214pnpm test:watch # Watch mode 215pnpm test:coverage # With coverage report 216pnpm lint # ESLint 217pnpm typecheck # TypeScript strict mode check 218``` 219 220See [CONTRIBUTING.md](https://github.com/singi-labs/.github/blob/main/CONTRIBUTING.md) for branching strategy, commit format, and code review process. 221 222**Key standards:** 223 224- TypeScript strict mode (no `any`, no `@ts-ignore`) 225- All endpoints validate input with Zod schemas 226- All user content sanitized with DOMPurify 227- Test-driven development (tests written before implementation) 228- Conventional commits enforced (`type(scope): description`) 229 230--- 231 232## Deployment 233 234```bash 235docker pull ghcr.io/singi-labs/barazo-api:latest 236``` 237 238See [barazo-deploy](https://github.com/singi-labs/barazo-deploy) for full deployment templates. 239 240--- 241 242## Related Repositories 243 244| Repository | Description | License | 245| ------------------------------------------------------------------ | --------------------------------------------- | ------- | 246| [barazo-web](https://github.com/singi-labs/barazo-web) | Forum frontend (Next.js, Tailwind) | MIT | 247| [barazo-lexicons](https://github.com/singi-labs/barazo-lexicons) | AT Protocol lexicon schemas + generated types | MIT | 248| [barazo-deploy](https://github.com/singi-labs/barazo-deploy) | Docker Compose deployment templates | MIT | 249| [barazo-website](https://github.com/singi-labs/barazo-website) | Marketing + documentation site | MIT | 250 251--- 252 253## Community 254 255- **Website:** [barazo.forum](https://barazo.forum) 256- **Discussions:** [GitHub Discussions](https://github.com/orgs/singi-labs/discussions) 257- **Issues:** [Report bugs](https://github.com/singi-labs/barazo-api/issues) 258 259--- 260 261## License 262 263**AGPL-3.0** -- Server-side copyleft. Anyone running a modified version as a hosted service must share their changes. 264 265See [LICENSE](LICENSE) for full terms. 266 267--- 268 269Made with ♥ in 🇪🇺 by [Singi Labs](https://singi.dev)