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