Saltar a contenido

FOLDER_STRUCTURE.md

Estructura de Carpetas IA-Ready

1. Principio

La estructura de carpetas define responsabilidades.
Los agentes IA no deben mezclar dominios ni escribir código en cualquier lugar.

2. Estructura recomendada

project/
├── CLAUDE.md                        ← carga automática de sesión IA
├── agents/
│   ├── ORCHESTRATOR.md
│   ├── BACKEND_AGENT.md
│   ├── FRONTEND_AGENT.md
│   ├── DEVOPS_AGENT.md
│   ├── SECURITY_AGENT.md
│   └── QA_AGENT.md
├── docs/
│   ├── PROJECT_CONTEXT.md
│   ├── PROJECT_STATUS.md            ← estado vivo del proyecto
│   ├── NEXT_ACTION.md               ← próxima acción concreta
│   ├── BACKLOG.md                   ← features pendientes de asignar
│   ├── ARCHITECTURE.md
│   ├── STACK.md
│   ├── RULES.md
│   ├── FOLDER_STRUCTURE.md
│   ├── WORKFLOW.md
│   ├── RBAC.md
│   ├── API_GUIDELINES.md
│   ├── GIT_WORKFLOW.md
│   ├── SPRINT_0.md
│   ├── adr/
│   │   └── ADR_INDEX.md             ← índice de decisiones arquitectónicas
│   └── sprints/
│       ├── SPRINT_INDEX.md          ← registro histórico de sprints
│       └── SPRINT-XX.md             ← instancias generadas desde templates/
├── backend/
│   ├── apps/
│   │   ├── core_api/            ← middleware tenant, JWT, feature flags, seguridad
│   │   ├── app_empresas/        ← Empresa, Sucursal, UsuarioEmpresaSucursal
│   │   ├── app_suscripciones/   ← planes, Feature Flags (schema public)
│   │   ├── app_inventario/      ← Producto, Stock, PlantillaRubro, importador
│   │   └── app_caja/            ← Caja, Venta, cierre ciego
│   │       ├── models.py
│   │       ├── services.py      ← lógica de negocio (cierre ciego, sync offline)
│   │       ├── selectors.py     ← queries complejas de lectura
│   │       ├── serializers.py
│   │       ├── views.py
│   │       ├── permissions.py
│   │       ├── tasks.py         ← tareas Celery (importador, sync ventas offline)
│   │       ├── urls.py
│   │       └── tests/
│   ├── config/
│   │   ├── settings/
│   │   │   ├── base.py          ← configuración común a todos los entornos
│   │   │   ├── development.py   ← extiende base: debug, hot reload, puertos expuestos
│   │   │   └── production.py    ← extiende base: Gunicorn, SSL, logging, sin DEBUG
│   │   ├── urls.py
│   │   ├── wsgi.py
│   │   └── asgi.py
│   ├── manage.py
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   ├── features/
│   │   │   ├── auth/            ← Login, sesión
│   │   │   ├── dashboard/       ← Dashboard principal
│   │   │   └── onboarding/      ← Wizard de configuración inicial del tenant
│   │   ├── hooks/
│   │   ├── lib/
│   │   ├── routes/
│   │   ├── services/            ← api.ts — cliente axios
│   │   ├── stores/              ← authStore.ts y futuros stores Zustand
│   │   └── types/
│   ├── package.json
│   └── vite.config.ts
├── docker/
│   ├── nginx/
│   └── scripts/
├── media/
│   └── imports/
│       └── tenant_X/                ← archivos subidos por tenant, eliminados post-proceso
├── docker-compose.yml
├── checklists/
│   ├── ARCHITECTURE_CHECKLIST.md
│   └── RELEASE_READINESS_CHECKLIST.md
├── templates/
│   ├── FEATURE_SPEC_TEMPLATE.md
│   ├── SPRINT_TEMPLATE.md           ← template para Sprint 1 en adelante
│   ├── ADR_TEMPLATE.md
│   └── PR_CHECKLIST.md
└── README.md

3. Responsabilidades por carpeta

Carpeta Responsabilidad Agente principal
agents/ Instrucciones operativas para agentes IA Orchestrator
docs/ Source of truth documental Orchestrator
docs/adr/ Registro de decisiones arquitectónicas Orchestrator
docs/sprints/ Historial de sprints cerrados Orchestrator
backend/ API, modelos, services, permisos Backend Agent
frontend/ UI, rutas, estado cliente, integración API Frontend Agent
docker/ Infraestructura local y despliegue DevOps Agent
checklists/ Validaciones de calidad QA + Orchestrator
templates/ Plantillas reutilizables para features, sprints y ADRs Orchestrator

4. Reglas de separación

  • frontend/ no contiene lógica de negocio crítica.
  • backend/apps/[domain]/services.py contiene reglas de negocio.
  • backend/apps/[domain]/selectors.py contiene queries complejas de lectura.
  • backend/apps/[domain]/permissions.py contiene permisos específicos.
  • frontend/src/features/[domain] agrupa pantallas y componentes por dominio.
  • frontend/src/components solo contiene componentes compartidos.

5. Prohibiciones

  • No crear utils.py gigante con lógica mezclada.
  • No crear components/misc.
  • No crear endpoints dentro de archivos que no correspondan.
  • No mezclar lógica de dominios.
  • No duplicar validaciones críticas entre frontend y backend.
  • No crear carpetas nuevas sin documentarlas acá.