Estructura del proyecto · Payment Emulator Lab

Traducción de docs/en/onboarding/project-structure.md, que es el original. Si discrepan, manda el inglés.

El repositorio es un espacio de trabajo de npm con tres aplicaciones. Comparten lockfile, no código. Su único contrato en ejecución es HTTP.

apps/
├── api/
│   ├── src/core/                  # runtime reutilizable de la API
│   ├── src/modules/               # áreas de negocio o técnicas acotadas
│   ├── src/providers/             # comportamiento y vocabulario de cada proveedor
│   ├── src/infrastructure/database/
│   ├── scripts/                   # semilla, compilador de escenarios, importador de contratos
│   └── test/                      # unitarias, de propiedades, de conformidad, de integración
├── console/
│   ├── app/core/                  # runtime de gateway, tabla y formato de la consola
│   ├── app/modules/               # definiciones de funcionalidad para el operador
│   ├── app/pages/                 # páginas finas con ruta
│   └── server/                    # BFF de Nitro y sesión sellada de la consola
└── checkout/
    ├── app/core/                  # gateway del checkout y resolución de kits
    ├── app/components/            # armazón de checkout neutral
    ├── app/pages/                 # URLs con la forma de cada proveedor
    ├── providers/                 # kits visuales por proveedor
    └── server/                    # BFF de Nitro y sesión aparte del comprador
contracts/                         # importaciones de contratos oficiales
scenarios/                         # escenarios canónicos en JSON, editables
scripts/                           # humareda de aceptación de la pila entera
docs/
├── README.md                     # entrada bilingüe a la documentación
├── en/                           # guías, fidelidad e historial en inglés
└── es/                           # guías, fidelidad e historial en español
.agents/                           # reglas de arquitectura vinculantes
graphify-out/                      # instantánea de descubrimiento generada, histórica

#`apps/api/src/core`

Responsabilidad: el comportamiento que tiene que ser idéntico para todos los proveedores o para todos los módulos del plano de control.

Directorio	Es dueño de
`core/providers/`	`ProviderPlugin`, el registro, los errores canónicos y la conformidad estática
`core/idempotency/`	huella de la petición, lock consultivo de PostgreSQL, repetición y conflicto
`core/money/`	conversión entre decimales y unidades mínimas, y aritmética de comisiones
`core/http/`	arranque de la app, contrato de listados, paginación, forma de los errores
`core/security/`	hash de tokens, quién llama, roles y tachado

Mete código aquí sólo si de verdad es comportamiento compartido. Un ayudante que usa un solo módulo pertenece a ese módulo.

#`apps/api/src/modules`

Cada directorio es dueño de un área acotada de punta a punta:

Módulo	Responsabilidad
`gateway`	orquestación de la petición del proveedor, en el orden obligado
`payments`	ciclo de vida del intento canónico y el único camino de escritura de un pago
`ledger`	contabilidad del pago, asientos y apuntes, y liquidación
`applications`	inquilinos, credenciales de un solo uso, caducidad y alcance por fila
`users`	personas, contraseñas, sesiones y roles
`gateways`	activación por instalación y sobrescritura de números contables
`checkout`	vista pública del comprador e identidad opcional del cliente
`scenarios`	emparejado de escenarios propios y a medida, y resolución de versión
`webhooks`	registros del outbox transaccional e inspección desde el plano de control
`traces`	línea de tiempo de la petición, tachada
`banking`	fondeo y transferencias de carteras sintéticas
`banks`	el catálogo de instituciones: prefijo, dígitos, monedas
`bank-accounts`	contrapartes externas, de personas, cada una en un banco
`health`	sonda de salud sin autenticar

Los controladores declaran rutas y DTO; los servicios hacen el trabajo de varios pasos y usan el EntityManager de MikroORM directamente. No añadas interfaces de repositorio, agregados, eventos de dominio ni una división application/domain/infrastructure: este proyecto no usa DDD, explícitamente.

#Aplazamiento de disposición conocido

El contrato de arquitectura describe carpetas futuras models/, dto/, services/ y controllers/ por módulo. El árbol actual sigue teniendo todas las entidades centralizadas en src/infrastructure/database/entities/ y varios módulos planos. Está anotado en .agents/README.md. Sigue el módulo dueño actual cuando añadas comportamiento; no arranques una migración de carpetas de un módulo dentro de un cambio que no va de eso.

#`apps/api/src/providers`

Aquí vive la verdad HTTP de cada proveedor: rutas, validación contra el contrato, credenciales, vocabulario de estados y errores, formato de webhook y las dos traducciones entre lo canónico y el cable. Los plugins son objetos planos, sin dependencia de base de datos, libro mayor ni cola.

mercadopago/ y stripe/ son implementaciones enrutadas.
paypal/ enruta OAuth, Orders v2 y operaciones concretas de Payments v2.

Añadir un proveedor exige además una fila en el registro, cobertura de conformidad, un documento de fidelidad y —si tiene superficie de comprador— un kit de checkout. Sigue Añadir un proveedor.

#Ficheros de base de datos

Entidades: apps/api/src/infrastructure/database/entities/
Migraciones ordenadas: apps/api/src/infrastructure/database/migrations/
Configuración: apps/api/src/infrastructure/database/mikro-orm.config.ts
Punto de entrada de la CLI: apps/api/src/cli/migrate.ts

Las entidades son el modelo fuente; las migraciones son la historia explícita del esquema. Nunca edites una migración ya aplicada para representar un cambio nuevo.

#Consola Nuxt

apps/console/app/core/ es el runtime reutilizable de la consola. Las páginas y los componentes de módulo usan createRestGateway, useEntityCollection y RTable en vez de montar peticiones por su cuenta. Las rutas de Nitro bajo server/api/ son el único camino del navegador a la API y llevan la sesión sellada de quien entró.

Pon una funcionalidad nueva del operador en el app/modules/<área>/ más cercano; añade una página fina sólo si necesita ruta, y expón el endpoint de Nitro más pequeño que valga. Qué posee cada pieza de core/ —y las trampas de accesibilidad que existe para evitar— está en la consola.

#Checkout Nuxt

La disposición neutral va en apps/checkout/app/components/. La identidad y el flujo de cada proveedor van en apps/checkout/providers/<id>/. Las páginas de ruta mapean la forma de URL de cada proveedor a un kit, a través de app/core/kits.ts.

El checkout tiene su propia sesión de Nitro y su propio secreto. No importes de la consola ni del backend, y no metas PrimeVue aquí. Ver el checkout.

#Ficheros generados e históricos

apps/api/src/modules/scenarios/default-scenarios.ts se genera desde scenarios/**/*.json; edita el JSON y corre npm run scenario:compile.
dist/, .nuxt/, .output/, la salida de cobertura y node_modules/ son artefactos de compilación, no fuente.
graphify-out/ es salida generada de un árbol más viejo. No copies sus rutas src/... a la documentación actual sin verificarlas.
El src/ de la raíz sólo contiene un directorio de migraciones vacío y antiguo; no es el árbol de la API. El backend vivo está en apps/api/src/.

#apps/api/src/core

#apps/api/src/modules