openschool CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OpenSchool is a self-hosted school management system. It is a monorepo with two workspaces:

• backend/ — Go REST API (Gin framework)
• frontend/ — React SPA (Vite, TypeScript, Carbon Design System)

For anything beyond a quick fix, read further before making changes:

• docs/FEATURES.md — current feature list by module
• docs/ARCHITECTURE.md — component layout, full data model, external interfaces
• docs/adr/ — why behind non-obvious decisions (e.g. why positions aren't ThunderID roles, why the current-academic-year invariant exists) — check here before "fixing" something that looks wrong but is deliberate
• audit.md — known bugs/code-quality findings with severity; check it isn't already tracking whatever you just found before re-reporting it

Backend

Setup & Running

cd backend

# Start PostgreSQL
docker compose up -d

# Copy and configure environment
cp .env.example .env

# Run the API (migrations run automatically on startup)
go run ./cmd/api/main.go

The server starts on :8080. Migrations in db/migrations/ are applied via golang-migrate on every startup.

Building & Testing

cd backend
go build ./...
go vet ./...
go test ./...
go test ./path/to/package  # single package

CI (.github/workflows/backend-ci.yml) also runs staticcheck (blocking) and, informationally (not yet blocking — see the workflow file for why), govulncheck and a dead-code scan.

Database Workflow (sqlc)

SQL queries live in db/queries/. After editing queries or migrations, regenerate Go code:

cd backend
sqlc generate

Never edit files in db/sqlc/ directly — they are generated. Schema is inferred from db/migrations/.

Architecture

• cmd/api/main.go — entry point: loads env, runs migrations, connects DB, inits JWKS, starts Gin router
• internal/config/ — loads .env via godotenv
• internal/database/ — DSN builder, pgxpool connection, golang-migrate runner
• internal/middleware/ — AuthMiddleware (validates ThunderID-issued JWTs against JWKS) and RequireRole (per-route role gating)
• db/migrations/ — numbered up/down SQL migrations (golang-migrate format)
• db/queries/ — raw SQL queries annotated for sqlc
• db/sqlc/ — generated type-safe query code (do not edit)