gui.do / barazo-web
Barazo default frontend barazo.forum
fork atom
barazo-web / README.md
at main 175 lines 7.8 kB view raw view rendered
Guido X Jansen docs: update footer to Singi Labs with EU tagline (#206)
e56ba391
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 Web 10 11**Default frontend for Barazo forums -- accessible, themeable, replaceable.** 12 13[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)]() 14[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 15[![CI](https://github.com/singi-labs/barazo-web/actions/workflows/ci.yml/badge.svg)](https://github.com/singi-labs/barazo-web/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 default frontend for Barazo forums. Communicates with the [barazo-api](https://github.com/singi-labs/barazo-api) backend exclusively via REST API. Forum admins can customize the theme or replace this frontend entirely. WCAG 2.2 AA compliant from first commit. 26 27--- 28 29## Tech Stack 30 31| Component | Technology | 32| ------------------- | ---------------------------------------------------------------- | 33| Framework | Next.js 16 / React 19 / TypeScript (strict) | 34| Styling | TailwindCSS | 35| Components | shadcn/ui (Radix primitives) for admin; custom forum components | 36| Colors | Radix Colors (12-step system) + Flexoki (accent hues) | 37| Icons | Phosphor Icons (6 weights) | 38| Typography | Source Sans 3 / Source Code Pro (self-hosted, zero external DNS) | 39| Syntax highlighting | Shiki + Flexoki theme (SSR, dual light/dark) | 40| Testing | Vitest + vitest-axe + @axe-core/playwright | 41| Accessibility | WCAG 2.2 AA from first commit | 42| SEO | JSON-LD, OpenGraph, sitemaps, SSR | 43 44--- 45 46## Features 47 48**19 pages:** 49 50| Route | Page | 51| ------------------------ | --------------------------------------------------------- | 52| `/` | Topic list (home) | 53| `/[handle]/[rkey]` | Topic detail with threaded replies | 54| `/[handle]/[rkey]/edit` | Edit topic | 55| `/new` | Create new topic | 56| `/c/[slug]` | Category view | 57| `/search` | Full-text search | 58| `/profile/[handle]` | User profile | 59| `/settings` | User preferences (maturity, notifications, cross-posting) | 60| `/notifications` | Notification center | 61| `/accessibility` | Accessibility statement | 62| `/admin` | Admin dashboard | 63| `/admin/categories` | Category management | 64| `/admin/moderation` | Moderation queue | 65| `/admin/users` | User management | 66| `/admin/settings` | Community settings | 67| `/admin/content-ratings` | Content maturity settings | 68| `/admin/plugins` | Plugin management (placeholder) | 69| `/api/health` | Health endpoint | 70| Dynamic | Sitemap, robots.txt, OpenGraph image generation | 71 72**26 components:** 73 74- Forum: topic-list, topic-card, topic-view, topic-form, reply-card, reply-thread, category-nav 75- Editor: markdown-editor, markdown-content, markdown-preview 76- Interaction: reaction-bar, search-input, pagination, notification-bell, confirm-dialog, report-dialog 77- User: user-profile-card, reputation-badge, ban-indicator, self-label-indicator 78- Navigation: breadcrumbs, skip-links, theme-toggle, theme-provider 79- Layout: forum-layout, admin-layout 80 81**Core capabilities:** 82 83- Dark/light theme toggle 84- Block/mute user controls (portable via PDS) 85- Age gate dialog (GDPR minimum age 16) 86- Self-label indicators on posts 87- Breadcrumb navigation with JSON-LD structured data 88- OpenGraph image generation per topic 89- Sitemap + robots.txt 90- Skip links for keyboard navigation 91 92--- 93 94## Planned Features 95 96- Plugin management UI (page exists, functionality pending) 97- Stripe billing dashboard integration 98- PWA (push notifications, offline, add-to-home-screen) 99- AI feature UI (semantic search, AI moderation dashboard, translation) 100- Cross-community search aggregator UI 101 102--- 103 104## Quick Start 105 106**Prerequisites:** Node.js 24 LTS, pnpm, [barazo-api](https://github.com/singi-labs/barazo-api) running (or mock handlers). 107 108```bash 109git clone https://github.com/singi-labs/barazo-web.git 110cd barazo-web 111pnpm install 112 113# Run development server 114pnpm dev 115``` 116 117Open [http://localhost:3001](http://localhost:3001) to view in the browser. 118 119--- 120 121## Development 122 123```bash 124pnpm test # Run all tests 125pnpm lint # ESLint + a11y rules 126pnpm typecheck # TypeScript strict mode 127``` 128 129Three-tier accessibility testing: 130 1311. **Static analysis:** eslint-plugin-jsx-a11y (strict mode) 1322. **Unit tests:** vitest-axe on rendered components 1333. **Integration:** @axe-core/playwright in CI 134 135See [CONTRIBUTING.md](https://github.com/singi-labs/.github/blob/main/CONTRIBUTING.md) for branching strategy, commit format, and code review process. 136 137**Key standards:** 138 139- TypeScript strict mode (no `any`, no `@ts-ignore`) 140- Test-driven development (TDD) 141- WCAG 2.2 AA from first commit 142- Semantic HTML (`<nav>`, `<main>`, `<article>`, `<aside>`) 143- Keyboard navigation on all interactive elements 144- Conventional commits enforced 145 146--- 147 148## Related Repositories 149 150| Repository | Description | License | 151| ---------------------------------------------------------------- | --------------------------------------------- | -------- | 152| [barazo-api](https://github.com/singi-labs/barazo-api) | AppView backend (Fastify, firehose, REST API) | AGPL-3.0 | 153| [barazo-lexicons](https://github.com/singi-labs/barazo-lexicons) | AT Protocol lexicon schemas + generated types | MIT | 154| [barazo-deploy](https://github.com/singi-labs/barazo-deploy) | Docker Compose deployment templates | MIT | 155| [barazo-website](https://github.com/singi-labs/barazo-website) | Marketing + documentation site | MIT | 156 157--- 158 159## Community 160 161- **Website:** [barazo.forum](https://barazo.forum) 162- **Discussions:** [GitHub Discussions](https://github.com/orgs/singi-labs/discussions) 163- **Issues:** [Report bugs](https://github.com/singi-labs/barazo-web/issues) 164 165--- 166 167## License 168 169**MIT** 170 171See [LICENSE](LICENSE) for full terms. 172 173--- 174 175Made with ♥ in 🇪🇺 by [Singi Labs](https://singi.dev)