# 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/forgeo/forgebucket`