Barazo default frontend
barazo.forum
docs: replace CLAUDE.md with AGENTS.md
AGENTS.md is the cross-vendor standard for AI coding agent instructions.
Auto-generated from barazo-workspace/agents-md/ source files.
+76
-81
+76
AGENTS.md
+76
AGENTS.md
···
1
+
# Barazo Web -- Default Frontend
2
+
3
+
<!-- Auto-generated from barazo-workspace. To propose changes, edit the source:
4
+
https://github.com/barazo-forum/barazo-workspace/tree/main/agents-md -->
5
+
6
+
MIT | Part of [github.com/barazo-forum](https://github.com/barazo-forum)
7
+
8
+
The default frontend for Barazo forums. Communicates with the AppView backend exclusively via REST API. Forum admins can customize or replace entirely.
9
+
10
+
## Tech Stack
11
+
12
+
| Component | Technology |
13
+
| ------------------- | ---------------------------------------------------------------- |
14
+
| Framework | Next.js 16 / React 19 / TypeScript (strict) |
15
+
| Styling | TailwindCSS |
16
+
| Components | shadcn/ui (Radix primitives) for admin; custom forum components |
17
+
| Colors | Radix Colors (12-step system) + Flexoki accent hues |
18
+
| Icons | Phosphor Icons (6 weights) |
19
+
| Typography | Source Sans 3 / Source Code Pro (self-hosted, zero external DNS) |
20
+
| Syntax highlighting | Shiki + Flexoki theme (SSR, dual light/dark) |
21
+
| Testing | Vitest + vitest-axe + @axe-core/playwright |
22
+
| Accessibility | WCAG 2.2 AA from first commit |
23
+
| SEO | JSON-LD, OpenGraph, sitemaps, SSR |
24
+
25
+
## What This Repo Does
26
+
27
+
- Server-side rendered forum UI (topics, replies, categories, profiles, search)
28
+
- Admin dashboard (moderation, settings, branding) using shadcn/ui
29
+
- Communicates with barazo-api via REST API only (fully decoupled)
30
+
- Handles AT Protocol OAuth login flow (redirects to user's PDS)
31
+
- Markdown rendering for post content (sanitized)
32
+
33
+
## Frontend-Specific Standards
34
+
35
+
- WCAG 2.2 AA compliance from first commit -- eslint-plugin-jsx-a11y strict + vitest-axe + @axe-core/playwright in CI
36
+
- Semantic HTML -- correct elements (`<nav>`, `<main>`, `<article>`, `<aside>`), no div soup
37
+
- Keyboard navigation -- all interactive elements reachable and operable, visible focus indicators
38
+
- Radix primitives (via shadcn/ui) for complex interactive components -- no custom dropdowns, dialogs, etc.
39
+
- SEO -- JSON-LD structured data (DiscussionForumPosting, BreadcrumbList), OpenGraph + Twitter Cards, sitemaps, canonical URLs
40
+
- DOMPurify on all user-generated content rendering
41
+
42
+
---
43
+
44
+
## Project-Wide Standards
45
+
46
+
### About Barazo
47
+
48
+
Federated forum built on the [AT Protocol](https://atproto.com/). Portable identity, user-owned data, cross-community reputation.
49
+
50
+
- **Organization:** [github.com/barazo-forum](https://github.com/barazo-forum)
51
+
- **License:** AGPL-3.0 (backend) / MIT (frontend, lexicons, deploy, website)
52
+
- **Contributing:** See [CONTRIBUTING.md](https://github.com/barazo-forum/.github/blob/main/CONTRIBUTING.md)
53
+
54
+
### Coding Standards
55
+
56
+
1. **Test-Driven Development** -- write tests before implementation (Vitest).
57
+
2. **Strict TypeScript** -- `strict: true`, no `any`, no `@ts-ignore`.
58
+
3. **Conventional commits** -- `type(scope): description`.
59
+
4. **CI must pass** -- lint, typecheck, tests, security scan on every PR.
60
+
5. **Input validation** -- Zod schemas on all API inputs and firehose records.
61
+
6. **Output sanitization** -- DOMPurify on all user-generated content.
62
+
7. **No raw SQL** -- Drizzle ORM with parameterized queries only.
63
+
8. **Structured logging** -- Pino logger, never `console.log`.
64
+
9. **Accessibility** -- WCAG 2.2 AA, semantic HTML, keyboard navigable.
65
+
66
+
### Git Workflow
67
+
68
+
All changes go through Pull Requests -- never commit directly to `main`. Branch naming: `type/short-description` (e.g., `feat/add-reactions`, `fix/xss-sanitization`).
69
+
70
+
### AT Protocol Context
71
+
72
+
- Users own their data (stored on their Personal Data Server)
73
+
- The AppView (barazo-api) indexes data from the AT Protocol firehose
74
+
- Lexicons (`forum.barazo.*`) define the data schema contract
75
+
- Identity is portable via DIDs -- no vendor lock-in
76
+
- All record types are validated against lexicon schemas
-81
CLAUDE.md
-81
CLAUDE.md
···
1
-
# Barazo Web -- Default Frontend
2
-
3
-
MIT | Part of [github.com/barazo-forum](https://github.com/barazo-forum)
4
-
5
-
The default frontend for Barazo forums. Communicates with the AppView backend exclusively via REST API. Forum admins can customize or replace entirely.
6
-
7
-
## Tech Stack
8
-
9
-
| Component | Technology |
10
-
| ------------------- | ---------------------------------------------------------------- |
11
-
| Framework | Next.js 16 / React 19 / TypeScript (strict) |
12
-
| Styling | TailwindCSS |
13
-
| Components | shadcn/ui (Radix primitives) for admin; custom forum components |
14
-
| Colors | Radix Colors (12-step system) + Flexoki (accent hues) |
15
-
| Icons | Phosphor Icons (6 weights, replaces Lucide) |
16
-
| Typography | Source Sans 3 / Source Code Pro (self-hosted, zero external DNS) |
17
-
| Syntax highlighting | Shiki + Flexoki theme (SSR, dual light/dark) |
18
-
| Testing | Vitest + vitest-axe + @axe-core/playwright |
19
-
| Accessibility | WCAG 2.2 AA from first commit |
20
-
| SEO | JSON-LD, OpenGraph, sitemaps, SSR |
21
-
22
-
## What This Repo Does
23
-
24
-
- Server-side rendered forum UI (topics, replies, categories, profiles, search)
25
-
- Admin dashboard (moderation, settings, branding) using shadcn/ui
26
-
- Communicates with barazo-api via REST API only (fully decoupled)
27
-
- Handles AT Protocol OAuth login flow (redirects to user's PDS)
28
-
- Markdown rendering for post content (sanitized)
29
-
30
-
## Mandatory Standards
31
-
32
-
Read these before writing any code:
33
-
34
-
1. **Test-Driven Development** -- write tests BEFORE implementation. Use the `test-driven-development` skill.
35
-
2. **Strict TypeScript** -- `strict: true`, no `any`, no `@ts-ignore`.
36
-
3. **Accessibility** -- WCAG 2.2 AA from first commit. Pagination by default. eslint-plugin-jsx-a11y strict + vitest-axe + @axe-core/playwright in CI.
37
-
4. **SEO** -- JSON-LD structured data (DiscussionForumPosting, BreadcrumbList), OpenGraph + Twitter Cards, sitemaps, canonical URLs, robots.txt.
38
-
5. **Output sanitization** -- DOMPurify on all user-generated content. Prevent XSS.
39
-
6. **Conventional commits** -- `type(scope): description`.
40
-
7. **CI checks must pass** -- lint, typecheck, tests, a11y audit, Lighthouse CI on every PR.
41
-
8. **Semantic HTML** -- use correct elements (`<nav>`, `<main>`, `<article>`, `<aside>`). No `div` soup.
42
-
9. **Keyboard navigation** -- all interactive elements reachable and operable via keyboard. Visible focus indicators.
43
-
10. **Radix primitives** -- use Radix (via shadcn/ui) for complex interactive components. Don't build custom dropdowns, dialogs, etc.
44
-
45
-
## Git Workflow
46
-
47
-
- **Small changes** (typos, single-file fixes, config tweaks): commit directly to `main`
48
-
- **Substantial work** (new features, multi-file changes, refactors): always create a git worktree
49
-
50
-
## Workspace Docs
51
-
52
-
Architectural decisions and detailed standards live in the workspace, not in this repo. Load only what's relevant:
53
-
54
-
```
55
-
~/Documents/CoreNotes/Workspaces/Barazo/
56
-
├── decisions/frontend.md SEO patterns, accessibility decisions
57
-
├── decisions/features-and-ux.md MVP scope, onboarding, reactions
58
-
├── standards/shared.md TypeScript, CI/CD, testing, commits, code review
59
-
├── standards/frontend.md Components, SEO implementation, a11y testing tiers
60
-
└── research/05-data-models.md Lexicon schemas (for API response types)
61
-
```
62
-
63
-
## Execution Strategy
64
-
65
-
**Master plan:** `~/Documents/CoreNotes/Workspaces/Barazo/plans/2026-02-09-mvp-implementation.md`
66
-
67
-
Before starting any milestone, read the master plan's **Execution Strategy** section. It specifies:
68
-
69
-
- Which skill to invoke (`subagent-driven-development` or `executing-plans`)
70
-
- Which model to use per milestone (the plan has a per-milestone model map)
71
-
- Review gates (spec compliance + code quality) that must pass before marking tasks complete
72
-
73
-
**This repo's milestones (completed during P1):** Implementation milestones Web M1-M14 are internal to this repo and completed during P1 (Core MVP). Web M1-M3 use `opus` (scaffold, design system, auth -- establishes all patterns). Web M4-M14 use `sonnet` (follows established component and page patterns). Reviewers always use `sonnet`.
74
-
75
-
## Project Context
76
-
77
-
- **Project owner (Guido) is NOT a software engineer** -- Claude Code is the sole implementer
78
-
- All code must be production-quality from the first commit
79
-
- This frontend is the reference implementation; third parties may build alternatives
80
-
- Focus on AT Protocol patterns (not traditional forum patterns)
81
-
- Keep it simple (MVP mindset)