Estructura del repositorio

La raíz del proyecto contiene tres bloques principales: frontend/, backend/ y docs/. A continuación se describe cada uno.

Raíz

serconsa/
├── backend/                  # API REST FastAPI
├── frontend/                 # SPA React 19
├── docs/                     # Documentación (Docusaurus / markdown)
├── docker-compose.yml        # Desarrollo local
├── docker-compose.prod.yml   # Producción
├── .gitlab-ci.yml            # Pipeline CI/CD
├── AGENTS.md                 # Reglas de código obligatorias
├── README.md                 # Inicio rápido
└── .env.example              # Variables de entorno de ejemplo

Backend

backend/
├── app/
│   ├── api/
│   │   ├── v1/              # Routers por dominio
│   │   │   ├── router.py    # Registro central de routers
│   │   │   ├── budgets.py
│   │   │   ├── budget_items.py
│   │   │   ├── budget_breakdowns.py
│   │   │   ├── budget_actions.py
│   │   │   ├── budget_config.py
│   │   │   ├── budget_espacios.py
│   │   │   ├── budget_liquidacion.py
│   │   │   ├── budget_organize.py
│   │   │   ├── budget_reports.py
│   │   │   ├── budget_variables.py
│   │   │   ├── certifications.py
│   │   │   ├── auth.py
│   │   │   ├── users.py
│   │   │   ├── roles.py
│   │   │   └── ...
│   │   ├── deps.py          # Servicios inyectables
│   │   └── budget_ownership.py  # Validación de propiedad de presupuesto
│   ├── core/
│   │   ├── config.py        # Settings con pydantic-settings
│   │   ├── database.py      # Motor async SQLAlchemy
│   │   ├── security.py      # JWT, bcrypt, blacklist en Redis
│   │   ├── deps.py          # dependencias de auth/permisos
│   │   ├── exceptions.py    # Jerarquía de errores de dominio
│   │   └── redis.py         # Cliente Redis
│   ├── models/
│   │   ├── base.py          # Base, AuditMixin, SoftDeleteMixin, UUIDPrimaryKeyMixin
│   │   ├── budget.py
│   │   ├── budget_item.py
│   │   ├── budget_measurement.py
│   │   ├── budget_breakdown.py
│   │   ├── budget_variable.py
│   │   ├── certification.py
│   │   ├── user.py
│   │   ├── role.py
│   │   ├── permission.py
│   │   ├── project.py
│   │   └── ...
│   ├── repositories/        # Acceso a datos
│   ├── schemas/             # Pydantic request/response
│   ├── services/            # Lógica de negocio
│   └── main.py              # Punto de entrada FastAPI
├── alembic/
│   ├── env.py
│   ├── script.py.mako
│   └── versions/            # Migraciones
├── tests/                   # Tests pytest
├── pyproject.toml           # Dependencias y configuración de herramientas
├── alembic.ini              # Configuración Alembic
└── Dockerfile

Frontend

frontend/
├── src/
│   ├── api/                 # Clientes HTTP (axios) por dominio
│   │   ├── client.ts        # Instancia axios + interceptores
│   │   ├── auth.ts
│   │   ├── budgets.ts
│   │   └── ...
│   ├── components/          # Componentes React
│   │   ├── budgets/
│   │   ├── certifications/
│   │   ├── common/
│   │   └── ...
│   ├── hooks/               # TanStack Query hooks
│   │   ├── useBudgets.ts
│   │   ├── useBudgetItems.ts
│   │   └── ...
│   ├── pages/               # Vistas por ruta
│   ├── stores/              # Zustand stores
│   ├── layouts/             # Shell, menú, workspace
│   ├── types/               # TypeScript interfaces
│   ├── utils/               # Helpers y formateadores
│   └── styles/              # CSS tokens y tema
├── public/
├── index.html
├── package.json
├── vite.config.ts
├── vitest.config.ts
└── Dockerfile

Documentación

docs/
├── dev/                     # Esta guía de desarrollador
├── desarrollo/              # Documentación previa (backend.md, frontend.md, arquitectura.md)
├── api/                     # Documentación de API
├── operaciones/             # Despliegue
├── usuario/                 # Guías de usuario
└── imitacion-presto/        # Especificación funcional de Presto

Reglas de ubicación

Un router FastAPI por recurso en backend/app/api/v1/.
Un servicio por caso de uso en backend/app/services/.
Un repositorio por agregado en backend/app/repositories/.
Un modelo por tabla en backend/app/models/.
Un hook TanStack Query por dominio en frontend/src/hooks/.
Un cliente API por dominio en frontend/src/api/.

Siguiente: Modelos de datos