# Conventions — Talos Access ## Code Style ### Python (Backend) - **Format:** Black-compatible (single quotes for strings, 120 char lines) - **Imports:** stdlib → third-party → project, separated by blank lines - **Naming:** `snake_case` for functions/variables, `PascalCase` for classes, `UPPER_CASE` for constants - **Types:** Type hints on all function signatures - **Error handling:** FastAPI `HTTPException` with explicit status codes - **DB:** SQLAlchemy ORM queries in endpoint functions, no repository layer ### TypeScript/React (Frontend) - **Format:** Prettier-compatible (single quotes, trailing commas) - **Naming:** `camelCase` for variables/functions, `PascalCase` for components/types - **Imports:** Named imports preferred over default - **State:** Zustand for global state, `useState`/`useEffect` for local - **CSS:** Tailwind utility classes, no CSS modules - **API calls:** Service modules under `src/services/` returning typed responses ## Project Structure ``` backend/ app/ api/v1/endpoints/ # Route handlers (one file per resource) core/ # Config, security, database setup dependencies/ # FastAPI dependency injection middleware/ # RBAC, plan gate models/ # SQLAlchemy ORM models schemas/ # Pydantic request/response schemas utils/ # Shared utilities alembic/versions/ # Database migrations frontend/ src/ components/ # Reusable UI components pages/ # Route-level page components services/ # API client functions store/ # Zustand stores types/ # TypeScript interfaces utils/ # Helper functions ``` ## Commit Conventions - Prefix: `feat:` (feature), `fix:` (bugfix), `docs:` (documentation), `test:` (tests), `refactor:` (code change), `chore:` (tooling) - Description in Spanish (present tense, imperative) - Example: `feat: agrega calendario de feriados con bloqueo de asistencia` ## Database Migrations - Prefix: `NNN_short_description.py` - `upgrade()` is additive only (no destructive changes without documented data migration) - `downgrade()` reverses the upgrade - Each migration is a single atomic change