Estructura backend - NestJS
Notas sobre la Estructura
Organización Modular
/common: Cross-cutting concerns que afectan toda la aplicación/config: Configuración centralizada y validada/core: Servicios fundamentales del sistema/modules: Lógica de negocio organizada por dominio/infrastructure: Servicios técnicos y de infraestructura/shared: Código compartido entre módulos
Módulos de Dominio
Cada módulo sigue la estructura:
- Controllers: Manejo de HTTP requests
- Services: Lógica de negocio
- Repositories: Acceso a datos
- Entities: Modelos de dominio
- DTOs: Validación de entrada/salida
- Interfaces: Contratos y tipos
- Events: Eventos del dominio (si aplica)
Principios SOLID
- Single Responsibility: Cada servicio tiene una responsabilidad clara
- Open/Closed: Extensible mediante interfaces y herencia
- Liskov Substitution: Uso de abstracciones (providers base)
- Interface Segregation: Interfaces específicas por contexto
- Dependency Inversion: Inyección de dependencias de NestJS
Testing
- Tests unitarios junto al código o en
/test/unit - Tests de integración en
/test/integration - Tests E2E en
/test/e2e - Fixtures y utilidades compartidas
Repositorios
- Abstracción del acceso a datos
- Facilita migración futura de Firebase
- Operaciones CRUD estandarizadas
Servicios
- Lógica de negocio pura
- Sin dependencias directas de HTTP
- Testeable de forma aislada
Guards y Decoradores
- Reutilizables en toda la aplicación
- Separación de concerns de seguridad
- Metadata-driven
Configuración
- Variables de entorno validadas
- Configuración tipada
- Separada por dominios
Esta estructura permite:
- Escalabilidad horizontal y vertical
- Fácil testing y mantenimiento
- Onboarding rápido de desarrolladores
- Migración gradual de componentes
- Cumplimiento de mejores prácticas de NestJS
prompts-backend/
├── .cursorrules # (Opcional - específico para Cursor IDE)
├── .env # Variables de entorno
├── .env.example # Plantilla de variables de entorno
├── .eslintrc.js # Configuración ESLint
├── .gitignore # Archivos ignorados por Git
├── .prettierrc # Configuración Prettier
├── nest-cli.json # Configuración NestJS CLI
├── package.json # Dependencias y scripts
├── tsconfig.json # Configuración TypeScript
├── tsconfig.build.json # Configuración TypeScript para build
├── docker/
│ ├── Dockerfile # Dockerfile para producción
│ ├── Dockerfile.dev # Dockerfile para desarrollo
│ └── docker-compose.yml # Composición de servicios
├── src/
│ ├── main.ts # Punto de entrada de la aplicación
│ ├── app.module.ts # Módulo principal
│ ├── common/ # Elementos comunes compartidos (cross-cutting concerns)
│ │ ├── constants/
│ │ │ ├── api.constants.ts
│ │ │ ├── error-codes.constants.ts
│ │ │ ├── messages.constants.ts
│ │ │ └── index.ts
│ │ ├── decorators/
│ │ │ ├── api-key.decorator.ts
│ │ │ ├── current-user.decorator.ts
│ │ │ ├── rate-limit.decorator.ts
│ │ │ ├── roles.decorator.ts
│ │ │ ├── public.decorator.ts
│ │ │ └── index.ts
│ │ ├── dto/
│ │ │ ├── pagination.dto.ts
│ │ │ ├── response.dto.ts
│ │ │ ├── base-query.dto.ts
│ │ │ └── index.ts
│ │ ├── exceptions/
│ │ │ ├── business.exception.ts
│ │ │ ├── validation.exception.ts
│ │ │ ├── unauthorized.exception.ts
│ │ │ ├── not-found.exception.ts
│ │ │ └── index.ts
│ │ ├── filters/
│ │ │ ├── http-exception.filter.ts
│ │ │ ├── all-exceptions.filter.ts
│ │ │ ├── validation-exception.filter.ts
│ │ │ └── index.ts
│ │ ├── guards/
│ │ │ ├── jwt-auth.guard.ts
│ │ │ ├── api-key.guard.ts
│ │ │ ├── plan.guard.ts
│ │ │ ├── roles.guard.ts
│ │ │ ├── rate-limit.guard.ts
│ │ │ └── index.ts
│ │ ├── interceptors/
│ │ │ ├── logging.interceptor.ts
│ │ │ ├── transform.interceptor.ts
│ │ │ ├── timeout.interceptor.ts
│ │ │ ├── cache.interceptor.ts
│ │ │ └── index.ts
│ │ ├── interfaces/
│ │ │ ├── request.interface.ts
│ │ │ ├── response.interface.ts
│ │ │ ├── pagination.interface.ts
│ │ │ └── index.ts
│ │ ├── middlewares/
│ │ │ ├── logger.middleware.ts
│ │ │ ├── cors.middleware.ts
│ │ │ ├── security.middleware.ts
│ │ │ └── index.ts
│ │ ├── pipes/
│ │ │ ├── validation.pipe.ts
│ │ │ ├── parse-object-id.pipe.ts
│ │ │ ├── transform.pipe.ts
│ │ │ └── index.ts
│ │ ├── types/
│ │ │ ├── express.d.ts
│ │ │ ├── common.types.ts
│ │ │ └── index.ts
│ │ └── utils/
│ │ ├── pagination.util.ts
│ │ ├── response.util.ts
│ │ └── index.ts
│ ├── config/ # Configuración modular
│ │ ├── config.module.ts
│ │ ├── configurations/
│ │ │ ├── app.config.ts
│ │ │ ├── database.config.ts
│ │ │ ├── auth.config.ts
│ │ │ ├── redis.config.ts
│ │ │ ├── llm.config.ts
│ │ │ ├── storage.config.ts
│ │ │ ├── queue.config.ts
│ │ │ └── monitoring.config.ts
│ │ ├── validation/
│ │ │ ├── env.validation.ts
│ │ │ └── index.ts
│ │ └── index.ts
│ ├── core/ # Funcionalidad central del sistema
│ │ ├── database/
│ │ │ ├── database.module.ts
│ │ │ ├── database.service.ts
│ │ │ └── index.ts
│ │ ├── logger/
│ │ │ ├── logger.module.ts
│ │ │ ├── logger.service.ts
│ │ │ └── index.ts
│ │ ├── cache/
│ │ │ ├── cache.module.ts
│ │ │ ├── cache.service.ts
│ │ │ └── index.ts
│ │ └── health/
│ │ ├── health.module.ts
│ │ ├── health.controller.ts
│ │ └── index.ts
│ ├── modules/ # Módulos de dominio de negocio
│ │ ├── auth/
│ │ │ ├── auth.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── auth.controller.ts
│ │ │ │ ├── auth.controller.spec.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── auth.service.ts
│ │ │ │ ├── auth.service.spec.ts
│ │ │ │ ├── token.service.ts
│ │ │ │ ├── password.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── strategies/
│ │ │ │ ├── jwt.strategy.ts
│ │ │ │ ├── local.strategy.ts
│ │ │ │ ├── api-key.strategy.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── login.dto.ts
│ │ │ │ ├── register.dto.ts
│ │ │ │ ├── reset-password.dto.ts
│ │ │ │ ├── change-password.dto.ts
│ │ │ │ ├── refresh-token.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── session.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── jwt-payload.interface.ts
│ │ │ │ ├── auth-response.interface.ts
│ │ │ │ └── index.ts
│ │ │ ├── guards/
│ │ │ │ ├── local-auth.guard.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── users/
│ │ │ ├── users.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── users.controller.ts
│ │ │ │ ├── profile.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── users.service.ts
│ │ │ │ ├── profile.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── repositories/
│ │ │ │ ├── users.repository.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── user.entity.ts
│ │ │ │ ├── profile.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── create-user.dto.ts
│ │ │ │ ├── update-user.dto.ts
│ │ │ │ ├── update-profile.dto.ts
│ │ │ │ ├── user-query.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── user.interface.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── prompts/
│ │ │ ├── prompts.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── prompts.controller.ts
│ │ │ │ ├── prompt-templates.controller.ts
│ │ │ │ ├── prompt-execution.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── prompts.service.ts
│ │ │ │ ├── prompt-optimization.service.ts
│ │ │ │ ├── prompt-validation.service.ts
│ │ │ │ ├── prompt-execution.service.ts
│ │ │ │ ├── prompt-templates.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── repositories/
│ │ │ │ ├── prompts.repository.ts
│ │ │ │ ├── prompt-templates.repository.ts
│ │ │ │ ├── prompt-history.repository.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── prompt.entity.ts
│ │ │ │ ├── prompt-template.entity.ts
│ │ │ │ ├── prompt-execution.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── create-prompt.dto.ts
│ │ │ │ ├── update-prompt.dto.ts
│ │ │ │ ├── execute-prompt.dto.ts
│ │ │ │ ├── optimize-prompt.dto.ts
│ │ │ │ ├── prompt-query.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── prompt.interface.ts
│ │ │ │ ├── optimization.interface.ts
│ │ │ │ └── index.ts
│ │ │ ├── events/
│ │ │ │ ├── prompt-created.event.ts
│ │ │ │ ├── prompt-executed.event.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── flows/
│ │ │ ├── flows.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── flows.controller.ts
│ │ │ │ ├── flow-execution.controller.ts
│ │ │ │ ├── flow-templates.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── flows.service.ts
│ │ │ │ ├── flow-executor.service.ts
│ │ │ │ ├── flow-validator.service.ts
│ │ │ │ ├── block-factory.service.ts
│ │ │ │ ├── flow-engine.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── repositories/
│ │ │ │ ├── flows.repository.ts
│ │ │ │ ├── flow-executions.repository.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── flow.entity.ts
│ │ │ │ ├── block.entity.ts
│ │ │ │ ├── connection.entity.ts
│ │ │ │ ├── flow-execution.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── create-flow.dto.ts
│ │ │ │ ├── update-flow.dto.ts
│ │ │ │ ├── execute-flow.dto.ts
│ │ │ │ ├── flow-query.dto.ts
│ │ │ │ ├── block.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── flow.interface.ts
│ │ │ │ ├── block.interface.ts
│ │ │ │ ├── execution-context.interface.ts
│ │ │ │ └── index.ts
│ │ │ ├── blocks/
│ │ │ │ ├── base-block.ts
│ │ │ │ ├── prompt-block.ts
│ │ │ │ ├── conditional-block.ts
│ │ │ │ ├── loop-block.ts
│ │ │ │ ├── input-block.ts
│ │ │ │ ├── output-block.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── credits/
│ │ │ ├── credits.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── credits.controller.ts
│ │ │ │ ├── transactions.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── credits.service.ts
│ │ │ │ ├── transaction.service.ts
│ │ │ │ ├── credit-calculator.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── repositories/
│ │ │ │ ├── credits.repository.ts
│ │ │ │ ├── transactions.repository.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── credit-balance.entity.ts
│ │ │ │ ├── transaction.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── purchase-credits.dto.ts
│ │ │ │ ├── transfer-credits.dto.ts
│ │ │ │ ├── transaction-query.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── credit.interface.ts
│ │ │ │ ├── transaction.interface.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── api-keys/
│ │ │ ├── api-keys.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── api-keys.controller.ts
│ │ │ │ ├── api-key-usage.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── api-keys.service.ts
│ │ │ │ ├── api-key-validation.service.ts
│ │ │ │ ├── api-key-usage.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── repositories/
│ │ │ │ ├── api-keys.repository.ts
│ │ │ │ ├── api-key-usage.repository.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── api-key.entity.ts
│ │ │ │ ├── api-key-usage.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── create-api-key.dto.ts
│ │ │ │ ├── update-api-key.dto.ts
│ │ │ │ ├── api-key-query.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── api-key.interface.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── llm/
│ │ │ ├── llm.module.ts
│ │ │ ├── services/
│ │ │ │ ├── llm.service.ts
│ │ │ │ ├── llm-router.service.ts
│ │ │ │ ├── llm-health.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── providers/
│ │ │ │ ├── base-provider.ts
│ │ │ │ ├── openai.provider.ts
│ │ │ │ ├── google.provider.ts
│ │ │ │ ├── amazon.provider.ts
│ │ │ │ ├── azure.provider.ts
│ │ │ │ └── index.ts
│ │ │ ├── adapters/
│ │ │ │ ├── vercel-sdk.adapter.ts
│ │ │ │ ├── response-normalizer.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── provider.interface.ts
│ │ │ │ ├── llm-response.interface.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── multimodal/
│ │ │ ├── multimodal.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── media.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── media.service.ts
│ │ │ │ ├── file-processor.service.ts
│ │ │ │ ├── media-validator.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── processors/
│ │ │ │ ├── image.processor.ts
│ │ │ │ ├── audio.processor.ts
│ │ │ │ ├── document.processor.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── upload-media.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── media.interface.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── subscriptions/
│ │ │ ├── subscriptions.module.ts
│ │ │ ├── controllers/
│ │ │ │ ├── subscriptions.controller.ts
│ │ │ │ ├── plans.controller.ts
│ │ │ │ └── index.ts
│ │ │ ├── services/
│ │ │ │ ├── subscriptions.service.ts
│ │ │ │ ├── plan-validator.service.ts
│ │ │ │ ├── billing.service.ts
│ │ │ │ └── index.ts
│ │ │ ├── repositories/
│ │ │ │ ├── subscriptions.repository.ts
│ │ │ │ ├── plans.repository.ts
│ │ │ │ └── index.ts
│ │ │ ├── entities/
│ │ │ │ ├── subscription.entity.ts
│ │ │ │ ├── plan.entity.ts
│ │ │ │ └── index.ts
│ │ │ ├── dto/
│ │ │ │ ├── create-subscription.dto.ts
│ │ │ │ ├── update-subscription.dto.ts
│ │ │ │ └── index.ts
│ │ │ ├── interfaces/
│ │ │ │ ├── subscription.interface.ts
│ │ │ │ ├── plan.interface.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ └── webhooks/
│ │ ├── webhooks.module.ts
│ │ ├── controllers/
│ │ │ ├── stripe-webhook.controller.ts
│ │ │ └── index.ts
│ │ ├── services/
│ │ │ ├── webhook-processor.service.ts
│ │ │ └── index.ts
│ │ └── index.ts
│ ├── infrastructure/ # Servicios de infraestructura
│ │ ├── infrastructure.module.ts
│ │ ├── firebase/
│ │ │ ├── firebase.module.ts
│ │ │ ├── firebase.service.ts
│ │ │ ├── firestore.service.ts
│ │ │ ├── firebase-auth.service.ts
│ │ │ └── index.ts
│ │ ├── redis/
│ │ │ ├── redis.module.ts
│ │ │ ├── redis.service.ts
│ │ │ ├── redis-cache.service.ts
│ │ │ └── index.ts
│ │ ├── queue/
│ │ │ ├── queue.module.ts
│ │ │ ├── queue.service.ts
│ │ │ ├── processors/
│ │ │ │ ├── base.processor.ts
│ │ │ │ ├── prompt.processor.ts
│ │ │ │ ├── flow.processor.ts
│ │ │ │ ├── media.processor.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── storage/
│ │ │ ├── storage.module.ts
│ │ │ ├── storage.service.ts
│ │ │ ├── providers/
│ │ │ │ ├── firebase-storage.provider.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ ├── monitoring/
│ │ │ ├── monitoring.module.ts
│ │ │ ├── monitoring.service.ts
│ │ │ ├── providers/
│ │ │ │ ├── new-relic.provider.ts
│ │ │ │ └── index.ts
│ │ │ └── index.ts
│ │ └── email/
│ │ ├── email.module.ts
│ │ ├── email.service.ts
│ │ ├── templates/
│ │ │ ├── welcome.template.ts
│ │ │ ├── reset-password.template.ts
│ │ │ └── index.ts
│ │ └── index.ts
│ ├── shared/ # Servicios y utilidades compartidas
│ │ ├── shared.module.ts
│ │ ├── services/
│ │ │ ├── encryption.service.ts
│ │ │ ├── validation.service.ts
│ │ │ ├── transformation.service.ts
│ │ │ └── index.ts
│ │ ├── utils/
│ │ │ ├── crypto.util.ts
│ │ │ ├── date.util.ts
│ │ │ ├── string.util.ts
│ │ │ ├── validation.util.ts
│ │ │ └── index.ts
│ │ └── index.ts
│ └── database/ # Capa de base de datos (si se migra de Firebase)
│ ├── migrations/
│ ├── seeds/
│ └── schemas/
├── test/ # Tests organizados por tipo
│ ├── unit/
│ │ ├── services/
│ │ │ ├── auth.service.spec.ts
│ │ │ ├── prompts.service.spec.ts
│ │ │ └── flows.service.spec.ts
│ │ ├── controllers/
│ │ │ ├── auth.controller.spec.ts
│ │ │ └── prompts.controller.spec.ts
│ │ └── utils/
│ │ └── crypto.util.spec.ts
│ ├── integration/
│ │ ├── auth/
│ │ │ └── auth.integration.spec.ts
│ │ ├── prompts/
│ │ │ └── prompts.integration.spec.ts
│ │ └── flows/
│ │ └── flows.integration.spec.ts
│ ├── e2e/
│ │ ├── app.e2e-spec.ts
│ │ ├── auth.e2e-spec.ts
│ │ └── prompts.e2e-spec.ts
│ ├── fixtures/
│ │ ├── users.fixture.ts
│ │ ├── prompts.fixture.ts
│ │ └── flows.fixture.ts
│ └── utils/
│ ├── test-setup.ts
│ └── test-helpers.ts
├── scripts/ # Scripts de utilidad
│ ├── seed.ts # Seed de base de datos
│ ├── generate-api-docs.ts
│ ├── check-env.ts
│ └── migrate.ts
└── docs/ # Documentación
├── api/
│ ├── swagger.yaml
│ └── postman-collection.json
├── architecture/
│ ├── diagrams/
│ └── decisions/
└── guides/
├── development.md
└── deployment.md