docs and tools

.cursor/rules/backend_frontend_sync.mdc

@@ -0,0 +1,19 @@
+---
+description: Constants and shared elements synchronization between backend and frontend
+alwaysApply: false
+---
+# Backend-to-Frontend Synchronization
+
+The backend is the source of truth. Frontend types and constants are generated/validated from backend definitions.
+
+## Two Mechanisms
+
+1. **OpenAPI → TypeScript**: API response types are generated from FastAPI's OpenAPI schema using `openapi-typescript`. Regenerate with `make generate-types-standalone` after changing Pydantic schemas.
+
+2. **Shared Constants**: `shared/constants.json` holds values needed by both sides (roles, statuses, validation rules). Backend validates this file matches its definitions at startup.
+
+## Key Principle
+
+Never manually define types or constants in the frontend that originate from the backend. Import from `generated/api.ts` or `shared/constants.json` instead.
+
+See `Makefile` for sync commands (`generate-types-standalone`, `check-types-fresh`, `check-constants`).

.githooks/pre-commit

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Pre-commit hook to ensure generated types and constants are up-to-date
+
+set -e
+
+echo "🔍 Checking shared constants..."
+cd backend && uv run python validate_constants.py
+cd ..
+
+echo "🔍 Checking if generated types are fresh..."
+
+# Check if api.ts is staged
+if git diff --cached --name-only | grep -q "frontend/app/generated/api.ts"; then
+    echo "✓ Generated types are staged"
+else
+    # Check if backend schema files have changed
+    if git diff --cached --name-only | grep -qE "backend/(schemas|models|routes)"; then
+        echo "⚠️  Backend schema files changed but generated types not staged."
+        echo "   Run 'make generate-types-standalone' and stage the changes."
+        echo ""
+        echo "   To skip this check (not recommended): git commit --no-verify"
+        exit 1
+    fi
+fi
+
+echo "✅ Pre-commit checks passed"
+

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install-backend install-frontend install backend frontend db db-stop db-ready db-seed dev test test-backend test-frontend test-e2e typecheck generate-types generate-types-standalone check-types-fresh check-constants
+.PHONY: install-backend install-frontend install setup-hooks backend frontend db db-stop db-ready db-seed dev test test-backend test-frontend test-e2e typecheck generate-types generate-types-standalone check-types-fresh check-constants
 
 -include .env
 export
@@ -9,7 +9,10 @@ install-backend:
 install-frontend:
 	cd frontend && npm install
 
-install: install-backend install-frontend
+install: install-backend install-frontend setup-hooks
+
+setup-hooks:
+	git config core.hooksPath .githooks
 
 backend:
 	cd backend && uv run uvicorn main:app --reload

backend/schemas.py

@@ -19,7 +19,7 @@ class UserResponse(BaseModel):
     """Response model for authenticated user info."""
     id: int
     email: str
-    roles: list[str]
+    guachachas: list[str]
     permissions: list[str]
 
 

frontend/app/generated/api.ts

@@ -601,8 +601,8 @@ export interface components {
             id: number;
             /** Email */
             email: string;
-            /** Roles */
-            roles: string[];
+            /** Guachachas */
+            guachachas: string[];
             /** Permissions */
             permissions: string[];
         };