Barazo API#

AT Protocol AppView backend for federated forums -- portable identity, user data ownership, cross-community reputation.

Overview#

The 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.

Tech Stack#

Route Modules#

15 route modules across 74 source files:

Database Schema#

15 schema modules (Drizzle ORM):

Features#

AT Protocol integration:

• OAuth authentication with any AT Protocol PDS
• Firehose subscription via Tap, filtered for forum.barazo.* collections
• Record validation (Zod) before indexing
• Portable block/mute records stored on user PDS
• Cross-posting to Bluesky (default on, toggleable per topic) and Frontpage (feature flag)
• Cross-post deletion lifecycle (topic delete cascades to cross-posts)
• Rich OpenGraph images for cross-posts (forum branding, topic title, category)
• Self-labels on topics and replies
• Two operating modes: single-forum or global aggregator (COMMUNITY_MODE=global)

Forum core:

• Topics CRUD with sorting (chronological, reactions, trending)
• Threaded replies CRUD
• Categories with parent-child hierarchy and per-category maturity ratings
• Configurable reaction types per community
• Full-text search (PostgreSQL tsvector + GIN index)
• Optional semantic search (pgvector, activated by EMBEDDING_URL)
• In-app and email notifications
• User profiles with PDS sync
• Cross-community reputation (activity counts across forums)
• User preferences (global and per-community)

Content maturity and age gating:

• Three-tier content maturity system: SFW, Mature, Adult
• Maturity ratings at both forum and category level
• Content maturity filtering based on user age declaration
• Age declaration as numeric value with jurisdiction-aware thresholds
• Admin-configurable jurisdiction country and age threshold

Moderation:

• Content reporting system
• First-post moderation queue
• Word and phrase blocklists
• Link spam detection
• Topic lock, pin, and delete
• User bans
• Moderation action log
• GDPR-compliant account deletion (identity event handling)

Community administration:

• Admin settings panel (name, description, branding, colors)
• Community setup wizard
• Admin-configurable onboarding fields (text, select, checkbox, etc.)
• User onboarding response submission and completion tracking
• Jurisdiction and age threshold configuration

Plugin system:

• Plugin-aware route architecture across all modules

Security:

• Zod validation on all API endpoints
• DOMPurify output sanitization on all user-generated content
• Helmet security headers (CSP, HSTS)
• Rate limiting on all endpoints
• Pino structured logging (no console.log)
• Sentry-compatible error monitoring (GlitchTip)

Planned Features#

• Semantic search activation (pgvector hybrid ranking) -- infrastructure installed, not yet wired
• AI-assisted moderation (spam and toxicity flagging)
• Stripe billing integration (P3)
• Multi-tenant SaaS management endpoints (P3)
• AT Protocol labeler integration (P4)
• Migration API endpoints (P5)
• Private categories (P4)
• Solved/accepted answer markers (P4)

API Documentation#

When running, interactive API docs are available at:

• Local: http://localhost:3000/docs
• Production: https://api.barazo.forum/docs

OpenAPI spec: GET /api/openapi.json

Quick Start#

Prerequisites: Node.js 24 LTS, pnpm, Docker + Docker Compose, AT Protocol PDS access (Bluesky or self-hosted).

git clone https://github.com/singi-labs/barazo-api.git
cd barazo-api
pnpm install

# Start PostgreSQL + Valkey
docker compose -f docker-compose.dev.yml up -d

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run development server
pnpm dev

Development#

pnpm test           # Run all tests
pnpm test:watch     # Watch mode
pnpm test:coverage  # With coverage report
pnpm lint           # ESLint
pnpm typecheck      # TypeScript strict mode check

See CONTRIBUTING.md for branching strategy, commit format, and code review process.

Key standards:

• TypeScript strict mode (no any, no @ts-ignore)
• All endpoints validate input with Zod schemas
• All user content sanitized with DOMPurify
• Test-driven development (tests written before implementation)
• Conventional commits enforced (type(scope): description)

Deployment#

docker pull ghcr.io/singi-labs/barazo-api:latest

See barazo-deploy for full deployment templates.

Related Repositories#

Community#

• Website: barazo.forum
• Discussions: GitHub Discussions
• Issues: Report bugs

License#

AGPL-3.0 -- Server-side copyleft. Anyone running a modified version as a hosted service must share their changes.

See LICENSE for full terms.

Made with ♥ in 🇪🇺 by Singi Labs