From fd16075306285be28233cd04d406e5ac990e8ff6 Mon Sep 17 00:00:00 2001
From: erangel1 <asgardlabs@proton.me>
Date: Wed, 6 May 2026 23:13:46 +0200
Subject: [PATCH] added claude.md file

---
 CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8b804b6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# ForgeBucket — Developer Guide
+
+Sovereign, federated Git collaboration platform.  
+Backend: Go 1.21+ · Frontend: React 18 + TypeScript + Vite · DB: PostgreSQL + XORM
+
+## Quick Start
+
+```bash
+cp .env.example .env          # fill in SESSION_SECRET and CSRF_SECRET
+make docker-up                # start PostgreSQL
+make migrate                  # run DB migrations
+make dev                      # Go on :8080 + Vite on :5173
+```
+
+## Architecture
+
+```
+cmd/forgebucket/     binary entry point
+internal/
+  api/               HTTP layer (Chi router, middleware, handlers)
+  domain/git/        sanitized git binary wrapper — no shell interpolation
+  domain/federation/ ActivityPub / ForgeFed implementation
+  domain/ci/         Forgejo Actions gRPC client
+  models/            XORM structs + migrations
+  config/            ENV-driven config, fails fast on missing secrets
+web/                 //go:embed target for built React SPA
+frontend/            React 18 + TypeScript + Vite + Tailwind
+```
+
+## Key Rules
+
+- **Git commands**: always `exec.Command("git", args...)` with discrete args — never build shell strings from user input
+- **Secrets**: never hardcode; all secrets come from environment variables
+- **CSRF**: all POST/PUT/DELETE routes require `X-CSRF-Token` header matching the session cookie
+- **Auth chain**: `Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler`
+- **8px grid**: all UI spacing must use multiples of 4px (xs) or 8px (sm) from `ui/tokens.ts`
+- **Touch targets**: minimum 44px for all interactive elements
+
+## Common Commands
+
+| Command | What it does |
+|---------|-------------|
+| `make dev` | Start both servers concurrently |
+| `make build` | Build frontend then embed into Go binary |
+| `make migrate` | Sync XORM schemas to PostgreSQL |
+| `make test` | Run Go tests + Vitest |
+| `make lint` | go vet + ESLint |
+| `make docker-up` | Start PostgreSQL via Docker Compose |
+
+## Environment Variables
+
+See `.env.example` for all required variables.  
+`SESSION_SECRET` ≥ 32 chars · `CSRF_SECRET` = exactly 32 chars.
+
+## Module Path
+
+`github.com/forgao/forgebucket`