{"id":50500849,"url":"https://github.com/singi-labs/barazo-api","last_synced_at":"2026-06-02T11:03:49.497Z","repository":{"id":337533899,"uuid":"1153568003","full_name":"singi-labs/barazo-api","owner":"singi-labs","description":"Barazo AppView backend","archived":false,"fork":false,"pushed_at":"2026-05-12T06:29:11.000Z","size":1828,"stargazers_count":10,"open_issues_count":32,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-12T08:29:50.414Z","etag":null,"topics":["api","api-rest","atprotocol","backend","fastify","firehose","forum"],"latest_commit_sha":null,"homepage":"https://barazo.forum","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/singi-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T12:59:57.000Z","updated_at":"2026-04-06T13:28:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/singi-labs/barazo-api","commit_stats":null,"previous_names":["atgora-forum/atgora-api","barazo-forum/barazo-api","singi-labs/barazo-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/singi-labs/barazo-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singi-labs%2Fbarazo-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singi-labs%2Fbarazo-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singi-labs%2Fbarazo-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singi-labs%2Fbarazo-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/singi-labs","download_url":"https://codeload.github.com/singi-labs/barazo-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singi-labs%2Fbarazo-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33818585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","atprotocol","backend","fastify","firehose","forum"],"created_at":"2026-06-02T11:03:48.406Z","updated_at":"2026-06-02T11:03:49.483Z","avatar_url":"https://github.com/singi-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/singi-labs/.github/main/assets/logo-dark.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/singi-labs/.github/main/assets/logo-light.svg\"\u003e\n  \u003cimg alt=\"Barazo Logo\" src=\"https://raw.githubusercontent.com/singi-labs/.github/main/assets/logo-dark.svg\" width=\"120\"\u003e\n\u003c/picture\u003e\n\n# Barazo API\n\n**AT Protocol AppView backend for federated forums -- portable identity, user data ownership, cross-community reputation.**\n\n[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)]()\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](https://opensource.org/licenses/AGPL-3.0)\n[![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)\n[![Node.js](https://img.shields.io/badge/node-24%20LTS-brightgreen)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)](https://www.typescriptlang.org/)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\nThe 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.\n\n---\n\n## Tech Stack\n\n| Component  | Technology                                                     |\n| ---------- | -------------------------------------------------------------- |\n| Runtime    | Node.js 24 LTS / TypeScript (strict mode)                      |\n| Framework  | Fastify 5                                                      |\n| Protocol   | @atproto/api, @atproto/oauth-client-node, @atproto/tap         |\n| Database   | PostgreSQL 16 + pgvector (Drizzle ORM, Drizzle Kit migrations) |\n| Cache      | Valkey (via ioredis)                                           |\n| Validation | Zod 4                                                          |\n| Testing    | Vitest 4 + Supertest + Testcontainers                          |\n| Logging    | Pino (structured)                                              |\n| Monitoring | GlitchTip (self-hosted, Sentry SDK-compatible)                 |\n| Security   | Helmet + DOMPurify + rate limiting + CSP/HSTS                  |\n| API docs   | @fastify/swagger + Scalar                                      |\n\n---\n\n## Route Modules\n\n15 route modules across 74 source files:\n\n| Module         | File                | Functionality                                                                                                            |\n| -------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| Auth           | `auth.ts`           | AT Protocol OAuth sign-in with any PDS                                                                                   |\n| OAuth Metadata | `oauth-metadata.ts` | OAuth discovery metadata endpoint                                                                                        |\n| Health         | `health.ts`         | Health check                                                                                                             |\n| Topics         | `topics.ts`         | CRUD, sorting (chronological / reactions / trending), cross-posting to Bluesky + Frontpage, self-labels                  |\n| Replies        | `replies.ts`        | CRUD threaded replies, self-labels                                                                                       |\n| Categories     | `categories.ts`     | CRUD with maturity ratings (SFW / Mature / Adult), parent-child hierarchy                                                |\n| Reactions      | `reactions.ts`      | Configurable reaction types per community                                                                                |\n| Search         | `search.ts`         | Full-text search (PostgreSQL tsvector + GIN index), optional semantic search via `EMBEDDING_URL`                         |\n| Profiles       | `profiles.ts`       | User profiles with PDS sync, cross-community reputation, age declaration                                                 |\n| Notifications  | `notifications.ts`  | In-app and email notification system                                                                                     |\n| Moderation     | `moderation.ts`     | Lock, pin, delete, ban, content reporting, first-post queue, word/phrase blocklists, link spam detection, mod action log |\n| Admin Settings | `admin-settings.ts` | Community settings, maturity rating, branding, jurisdiction + age threshold configuration                                |\n| Block / Mute   | `block-mute.ts`     | Block and mute users (portable via PDS records)                                                                          |\n| Onboarding     | `onboarding.ts`     | Admin-configurable community onboarding fields, user response submission and status tracking                             |\n| Setup          | `setup.ts`          | Initial community setup wizard                                                                                           |\n\n---\n\n## Database Schema\n\n15 schema modules (Drizzle ORM):\n\n| Schema                  | Purpose                                                  |\n| ----------------------- | -------------------------------------------------------- |\n| `users.ts`              | User accounts synced from PDS                            |\n| `topics.ts`             | Forum topics with maturity, self-labels                  |\n| `replies.ts`            | Threaded replies                                         |\n| `categories.ts`         | Category hierarchy with maturity ratings                 |\n| `reactions.ts`          | Reaction records                                         |\n| `reports.ts`            | Content reports                                          |\n| `notifications.ts`      | Notification records                                     |\n| `moderation-actions.ts` | Moderation action log                                    |\n| `cross-posts.ts`        | Bluesky + Frontpage cross-post tracking                  |\n| `community-settings.ts` | Per-community configuration, jurisdiction, age threshold |\n| `user-preferences.ts`   | Global and per-community user preferences                |\n| `onboarding-fields.ts`  | Admin-defined onboarding fields and user responses       |\n| `tracked-repos.ts`      | AT Protocol repo tracking state                          |\n| `firehose.ts`           | Firehose cursor and subscription state                   |\n| `index.ts`              | Schema barrel export                                     |\n\n---\n\n## Features\n\n**AT Protocol integration:**\n\n- OAuth authentication with any AT Protocol PDS\n- Firehose subscription via Tap, filtered for `forum.barazo.*` collections\n- Record validation (Zod) before indexing\n- Portable block/mute records stored on user PDS\n- Cross-posting to Bluesky (default on, toggleable per topic) and Frontpage (feature flag)\n- Cross-post deletion lifecycle (topic delete cascades to cross-posts)\n- Rich OpenGraph images for cross-posts (forum branding, topic title, category)\n- Self-labels on topics and replies\n- Two operating modes: single-forum or global aggregator (`COMMUNITY_MODE=global`)\n\n**Forum core:**\n\n- Topics CRUD with sorting (chronological, reactions, trending)\n- Threaded replies CRUD\n- Categories with parent-child hierarchy and per-category maturity ratings\n- Configurable reaction types per community\n- Full-text search (PostgreSQL tsvector + GIN index)\n- Optional semantic search (pgvector, activated by `EMBEDDING_URL`)\n- In-app and email notifications\n- User profiles with PDS sync\n- Cross-community reputation (activity counts across forums)\n- User preferences (global and per-community)\n\n**Content maturity and age gating:**\n\n- Three-tier content maturity system: SFW, Mature, Adult\n- Maturity ratings at both forum and category level\n- Content maturity filtering based on user age declaration\n- Age declaration as numeric value with jurisdiction-aware thresholds\n- Admin-configurable jurisdiction country and age threshold\n\n**Moderation:**\n\n- Content reporting system\n- First-post moderation queue\n- Word and phrase blocklists\n- Link spam detection\n- Topic lock, pin, and delete\n- User bans\n- Moderation action log\n- GDPR-compliant account deletion (identity event handling)\n\n**Community administration:**\n\n- Admin settings panel (name, description, branding, colors)\n- Community setup wizard\n- Admin-configurable onboarding fields (text, select, checkbox, etc.)\n- User onboarding response submission and completion tracking\n- Jurisdiction and age threshold configuration\n\n**Plugin system:**\n\n- Plugin-aware route architecture across all modules\n\n**Security:**\n\n- Zod validation on all API endpoints\n- DOMPurify output sanitization on all user-generated content\n- Helmet security headers (CSP, HSTS)\n- Rate limiting on all endpoints\n- Pino structured logging (no `console.log`)\n- Sentry-compatible error monitoring (GlitchTip)\n\n---\n\n## Planned Features\n\n- Semantic search activation (pgvector hybrid ranking) -- infrastructure installed, not yet wired\n- AI-assisted moderation (spam and toxicity flagging)\n- Stripe billing integration (P3)\n- Multi-tenant SaaS management endpoints (P3)\n- AT Protocol labeler integration (P4)\n- Migration API endpoints (P5)\n- Private categories (P4)\n- Solved/accepted answer markers (P4)\n\n---\n\n## API Documentation\n\nWhen running, interactive API docs are available at:\n\n- **Local:** `http://localhost:3000/docs`\n- **Production:** `https://api.barazo.forum/docs`\n\nOpenAPI spec: `GET /api/openapi.json`\n\n---\n\n## Quick Start\n\n**Prerequisites:** Node.js 24 LTS, pnpm, Docker + Docker Compose, AT Protocol PDS access (Bluesky or self-hosted).\n\n```bash\ngit clone https://github.com/singi-labs/barazo-api.git\ncd barazo-api\npnpm install\n\n# Start PostgreSQL + Valkey\ndocker compose -f docker-compose.dev.yml up -d\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your settings\n\n# Run development server\npnpm dev\n```\n\n---\n\n## Development\n\n```bash\npnpm test           # Run all tests\npnpm test:watch     # Watch mode\npnpm test:coverage  # With coverage report\npnpm lint           # ESLint\npnpm typecheck      # TypeScript strict mode check\n```\n\nSee [CONTRIBUTING.md](https://github.com/singi-labs/.github/blob/main/CONTRIBUTING.md) for branching strategy, commit format, and code review process.\n\n**Key standards:**\n\n- TypeScript strict mode (no `any`, no `@ts-ignore`)\n- All endpoints validate input with Zod schemas\n- All user content sanitized with DOMPurify\n- Test-driven development (tests written before implementation)\n- Conventional commits enforced (`type(scope): description`)\n\n---\n\n## Deployment\n\n```bash\ndocker pull ghcr.io/singi-labs/barazo-api:latest\n```\n\nSee [barazo-deploy](https://github.com/singi-labs/barazo-deploy) for full deployment templates.\n\n---\n\n## Related Repositories\n\n| Repository                                                         | Description                                   | License |\n| ------------------------------------------------------------------ | --------------------------------------------- | ------- |\n| [barazo-web](https://github.com/singi-labs/barazo-web)           | Forum frontend (Next.js, Tailwind)            | MIT     |\n| [barazo-lexicons](https://github.com/singi-labs/barazo-lexicons) | AT Protocol lexicon schemas + generated types | MIT     |\n| [barazo-deploy](https://github.com/singi-labs/barazo-deploy)     | Docker Compose deployment templates           | MIT     |\n| [barazo-website](https://github.com/singi-labs/barazo-website)   | Marketing + documentation site                | MIT     |\n\n---\n\n## Community\n\n- **Website:** [barazo.forum](https://barazo.forum)\n- **Discussions:** [GitHub Discussions](https://github.com/orgs/singi-labs/discussions)\n- **Issues:** [Report bugs](https://github.com/singi-labs/barazo-api/issues)\n\n---\n\n## License\n\n**AGPL-3.0** -- Server-side copyleft. Anyone running a modified version as a hosted service must share their changes.\n\nSee [LICENSE](LICENSE) for full terms.\n\n---\n\nMade with ♥ in 🇪🇺 by [Singi Labs](https://singi.dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingi-labs%2Fbarazo-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsingi-labs%2Fbarazo-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingi-labs%2Fbarazo-api/lists"}