Barazo default frontend
barazo.forum
docs: replace default Next.js README with project README (#19)
Replace create-next-app boilerplate with comprehensive project README
documenting alpha status, 356 tests, 19 pages, 26 components, tech
stack, and accessibility compliance.
authored by
Guido X Jansen
and committed by
GitHub
6421aabf
b0625cf9
+195
-20
+195
-20
README.md
+195
-20
README.md
···
1
-
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
1
+
<div align="center">
2
+
3
+
<picture>
4
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/barazo-forum/.github/main/assets/logo-dark.svg">
5
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/barazo-forum/.github/main/assets/logo-light.svg">
6
+
<img alt="Barazo Logo" src="https://raw.githubusercontent.com/barazo-forum/.github/main/assets/logo-dark.svg" width="120">
7
+
</picture>
8
+
9
+
# barazo-web
10
+
11
+
**Default frontend for Barazo forums**
12
+
13
+
[](https://opensource.org/licenses/MIT)
14
+
[](https://nodejs.org/)
15
+
[](https://www.typescriptlang.org/)
16
+
[](#testing)
17
+
18
+
</div>
19
+
20
+
---
21
+
22
+
## Status: Alpha
23
+
24
+
Core MVP UI implemented. 356 tests across 47 test files, all passing. WCAG 2.2 AA compliant.
25
+
26
+
**Completed:** P1 (Full forum UI) + P2.1/P2.2 (user preferences, self-labels, block/mute, age gate)
27
+
28
+
---
29
+
30
+
## What is this?
31
+
32
+
The default frontend for Barazo forums. Communicates with the [barazo-api](https://github.com/barazo-forum/barazo-api) backend exclusively via REST API. Forum admins can customize or replace this frontend entirely.
33
+
34
+
- **Server-side rendered** forum UI (topics, replies, categories, profiles, search)
35
+
- **Admin dashboard** (moderation, settings, branding, categories, users, content ratings)
36
+
- **AT Protocol OAuth** login flow (redirects to user's PDS)
37
+
- **Markdown rendering** for post content (sanitized via DOMPurify)
38
+
- **Accessibility-first** -- WCAG 2.2 AA from first commit
39
+
40
+
---
41
+
42
+
## Tech Stack
43
+
44
+
| Component | Technology |
45
+
| ------------------- | ---------------------------------------------------------------- |
46
+
| Framework | Next.js 16 / React 19 / TypeScript (strict) |
47
+
| Styling | TailwindCSS |
48
+
| Components | shadcn/ui (Radix primitives) for admin; custom forum components |
49
+
| Colors | Radix Colors (12-step system) + Flexoki (accent hues) |
50
+
| Icons | Phosphor Icons (6 weights) |
51
+
| Typography | Source Sans 3 / Source Code Pro (self-hosted, zero external DNS) |
52
+
| Syntax highlighting | Shiki + Flexoki theme (SSR, dual light/dark) |
53
+
| Testing | Vitest + vitest-axe + @axe-core/playwright |
54
+
| Accessibility | WCAG 2.2 AA from first commit |
55
+
| SEO | JSON-LD, OpenGraph, sitemaps, SSR |
56
+
57
+
---
58
+
59
+
## Implemented Features
60
+
61
+
**19 pages:**
62
+
63
+
| Route | Page |
64
+
| ------------------------ | --------------------------------------------------------- |
65
+
| `/` | Topic list (home) |
66
+
| `/t/[slug]/[rkey]` | Topic detail with threaded replies |
67
+
| `/t/[slug]/[rkey]/edit` | Edit topic |
68
+
| `/new` | Create new topic |
69
+
| `/c/[slug]` | Category view |
70
+
| `/search` | Full-text search |
71
+
| `/u/[handle]` | User profile |
72
+
| `/settings` | User preferences (maturity, notifications, cross-posting) |
73
+
| `/notifications` | Notification center |
74
+
| `/accessibility` | Accessibility statement |
75
+
| `/admin` | Admin dashboard |
76
+
| `/admin/categories` | Category management |
77
+
| `/admin/moderation` | Moderation queue |
78
+
| `/admin/users` | User management |
79
+
| `/admin/settings` | Community settings |
80
+
| `/admin/content-ratings` | Content maturity settings |
81
+
| `/admin/plugins` | Plugin management (placeholder) |
82
+
| `/api/health` | Health endpoint |
83
+
| Dynamic | Sitemap, robots.txt, OpenGraph image generation |
84
+
85
+
**26 components:**
86
+
87
+
- Forum: topic-list, topic-card, topic-view, topic-form, reply-card, reply-thread, category-nav
88
+
- Editor: markdown-editor, markdown-content, markdown-preview
89
+
- Interaction: reaction-bar, search-input, pagination, notification-bell, confirm-dialog, report-dialog
90
+
- User: user-profile-card, reputation-badge, ban-indicator, self-label-indicator
91
+
- Navigation: breadcrumbs, skip-links, theme-toggle, theme-provider
92
+
- Layout: forum-layout, admin-layout
93
+
94
+
**Core capabilities:**
95
+
96
+
- Dark/light theme toggle
97
+
- Block/mute user controls (portable via PDS)
98
+
- Age gate dialog (GDPR minimum age 16)
99
+
- Self-label indicators on posts
100
+
- Breadcrumb navigation with JSON-LD structured data
101
+
- OpenGraph image generation per topic
102
+
- Sitemap + robots.txt
103
+
- Skip links for keyboard navigation
104
+
105
+
## Planned Features
106
+
107
+
- Plugin management UI (page exists, functionality pending)
108
+
- Stripe billing dashboard integration
109
+
- PWA (push notifications, offline, add-to-home-screen)
110
+
- AI feature UI (semantic search, AI moderation dashboard, translation)
111
+
- Cross-community search aggregator UI
112
+
113
+
---
2
114
3
-
## Getting Started
115
+
## Testing
116
+
117
+
```
118
+
356 tests across 47 test files -- all passing
119
+
```
120
+
121
+
Three-tier accessibility testing:
4
122
5
-
First, run the development server:
123
+
1. **Static analysis:** eslint-plugin-jsx-a11y (strict mode)
124
+
2. **Unit tests:** vitest-axe on rendered components
125
+
3. **Integration:** @axe-core/playwright in CI
6
126
7
127
```bash
8
-
npm run dev
9
-
# or
10
-
yarn dev
11
-
# or
128
+
pnpm test # Run all tests
129
+
pnpm lint # ESLint + a11y rules
130
+
pnpm typecheck # TypeScript strict mode
131
+
```
132
+
133
+
---
134
+
135
+
## Prerequisites
136
+
137
+
- Node.js 24 LTS
138
+
- pnpm
139
+
- [barazo-api](https://github.com/barazo-forum/barazo-api) running (or use mock handlers for development)
140
+
141
+
---
142
+
143
+
## Quick Start
144
+
145
+
**Clone and install:**
146
+
147
+
```bash
148
+
git clone https://github.com/barazo-forum/barazo-web.git
149
+
cd barazo-web
150
+
pnpm install
151
+
```
152
+
153
+
**Run development server:**
154
+
155
+
```bash
12
156
pnpm dev
13
-
# or
14
-
bun dev
157
+
```
158
+
159
+
Open [http://localhost:3001](http://localhost:3001) to view in the browser.
160
+
161
+
**Run tests:**
162
+
163
+
```bash
164
+
pnpm test
165
+
pnpm lint
166
+
pnpm typecheck
15
167
```
16
168
17
-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
169
+
---
170
+
171
+
## Development
172
+
173
+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for full guidelines.
174
+
175
+
**Key standards:**
176
+
177
+
- TypeScript strict mode (no `any`, no `@ts-ignore`)
178
+
- Test-driven development (TDD)
179
+
- WCAG 2.2 AA from first commit
180
+
- Semantic HTML (`<nav>`, `<main>`, `<article>`, `<aside>`)
181
+
- Keyboard navigation on all interactive elements
182
+
- Conventional commits enforced
183
+
184
+
---
185
+
186
+
## License
187
+
188
+
**MIT** -- Encourages customization and theming. Forum admins can build entirely custom frontends.
18
189
19
-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
190
+
See [LICENSE](LICENSE) for full terms.
20
191
21
-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
192
+
---
22
193
23
-
## Learn More
194
+
## Related Repositories
24
195
25
-
To learn more about Next.js, take a look at the following resources:
196
+
- **[barazo-api](https://github.com/barazo-forum/barazo-api)** -- Backend (AGPL-3.0)
197
+
- **[barazo-lexicons](https://github.com/barazo-forum/barazo-lexicons)** -- AT Protocol schemas (MIT)
198
+
- **[barazo-deploy](https://github.com/barazo-forum/barazo-deploy)** -- Deployment templates (MIT)
199
+
- **[Organization](https://github.com/barazo-forum)** -- All repos
26
200
27
-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28
-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
201
+
---
29
202
30
-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
203
+
## Community
31
204
32
-
## Deploy on Vercel
205
+
- **Website:** [barazo.forum](https://barazo.forum) (coming soon)
206
+
- **Discussions:** [GitHub Discussions](https://github.com/orgs/barazo-forum/discussions)
207
+
- **Issues:** [Report bugs](https://github.com/barazo-forum/barazo-web/issues)
33
208
34
-
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
209
+
---
35
210
36
-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
211
+
(c) 2026 Barazo. Licensed under MIT.