project-structure-overview

Instruction file imported from lgsalinasp7/Amaxoft-copia (.cursor/rules/project-structure-overview.mdc). Copyright stays with the author.

Resumen de Estructura del Proyecto

Vista General

src/
├── 📦 modules/           # Dominios de negocio (Clean Architecture)
│   ├── core/            # Repositorios base
│   ├── quotations/      # Cotizaciones
│   ├── payments/        # Pagos
│   ├── users/           # Usuarios
│   ├── memberships/     # Membresías
│   ├── auth/            # Autenticación
│   ├── tenants/         # Multi-tenant
│   └── ordenes-trabajo/ # Órdenes (tenant)
│
├── 🔧 infrastructure/    # Servicios técnicos
│   ├── database/        # Prisma (main + tenants)
│   ├── neon/            # API de Neon
│   ├── email/           # Cola de emails
│   └── logging/         # Sistema de logs
│
├── 📋 registry/          # Configuración de productos
│   └── products/        # Definiciones de productos
│
├── 🎨 app/               # Next.js App Router
│   ├── api/             # API Routes
│   ├── (auth)/          # Páginas de auth
│   ├── (dashboard)/     # Dashboard admin
│   └── tenant/          # Dashboard tenants
│
├── 🧩 components/        # Componentes UI
├── 📚 lib/               # Utilidades
├── 🎣 hooks/             # Custom hooks
├── 📊 stores/            # Estado global (Zustand)
└── 📝 types/             # Tipos globales

Reglas de Oro

1. Módulos = Dominio de Negocio

Todo código de negocio va en src/modules/:

// ✅ Correcto
import { quotationService } from "@/modules/quotations";

// ❌ Incorrecto - NO crear servicios fuera de modules
import { quotationService } from "@/services/quotationService";

2. Estructura de un Módulo

mi-modulo/
├── types/          # ¿Qué datos?
├── repository/     # ¿Cómo accedo a BD?
├── services/       # ¿Qué lógica de negocio?
├── use-cases/      # ¿Cómo orquesto operaciones complejas?
├── index.ts        # Exports centralizados
└── README.md       # Documentación

3. Flujo de Dependencias

API Route → Use Case → Service → Repository → Prisma
    ↓           ↓          ↓
  Valida    Orquesta   Lógica de    Acceso a
  request   servicios   negocio       datos

4. Importaciones Correctas

// ✅ Desde módulo (barrel export)
import { userService, type CreateUserDTO } from "@/modules/users";

// ✅ Desde infrastructure
import { logger } from "@/infrastructure/logging";
import { prismaMain } from "@/infrastructure/database/prisma-main";

// ✅ Desde registry
import { getProduct, isFeatureEnabled } from "@/registry";

// ❌ NUNCA importar archivos internos directamente
import { UserService } from "@/modules/users/services/user.service";

5. Naming Conventions

Cuándo Crear Qué

Nuevo Dominio de Negocio

→ Crear módulo en src/modules/

Nuevo Servicio Técnico (BD, API externa, etc.)

→ Crear en src/infrastructure/

Nuevo Producto Multi-tenant

→ Ver .cursor/rules/multi-tenant-products.mdc para guía completa → Pasos resumidos:

1. Config en src/registry/products/
2. Schema en prisma/tenant-schemas/
3. Menú en TenantSidebar.tsx → menusByAppType
4. Páginas en src/app/tenant/[slug]/
5. Producto en BD con appType y createsTenant: true

Operación Compleja Multi-servicio

→ Crear Use Case en src/modules/[modulo]/use-cases/

Componente UI Reutilizable

→ Crear en src/components/

Estado Global

→ Crear store en src/stores/

Checklist para Nuevo Módulo

• Crear carpeta src/modules/mi-modulo/
• Crear types/mi-modulo.types.ts
• Crear repository/mi-modulo.repository.ts
• Crear services/mi-modulo.service.ts
• Crear index.ts con barrel exports
• Crear README.md con documentación
• Registrar en src/modules/index.ts
• (Opcional) Crear use-cases si hay operaciones complejas

Archivos de Reglas Relacionados

• modular-architecture.mdc - Cómo crear módulos
• product-registry.mdc - Cómo agregar productos
• multi-tenant-products.mdc - Guía completa para crear nuevos productos multi-tenant
• infrastructure-layer.mdc - Cómo usar infraestructura
• use-cases-pattern.mdc - Cómo crear use cases
• error-handling-standardization.mdc - Manejo de errores
• form-validation-system.mdc - Validación de formularios