File size: 2,263 Bytes
6aa6081
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
# 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