talos-access / docs /conventions.md
Greg
Claude Opus 4.7 (1M context)
Preparar despliegue en fly.io: monolito dockerizado + seeder demo
6aa6081
|
Raw History Blame Contribute Delete
2.26 kB
# 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