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