Estructura del Monorepo

El monorepo usa Turborepo v2 con pnpm workspaces. Todas las apps y packages comparten tipos y schemas sin duplicar código.

Estructura de directorios

nappai-fluency/
├── apps/
│   ├── web/          ← React 19 + Vite (frontend)
│   ├── api/          ← NestJS 11 + Prisma (backend)
│   ├── ai-backend/   ← Motor IA propio (ADR-010)
│   ├── e2e/          ← Playwright (tests E2E)
│   └── docs/         ← Este portal (Astro Starlight)
│
├── packages/
│   ├── shared-types/   ← Tipos TypeScript compartidos
│   └── shared-schemas/ ← Schemas Zod compartidos
│
├── turbo.json          ← Pipeline de tareas
├── pnpm-workspace.yaml ← Workspaces
└── package.json        ← Scripts raíz

Pipelines Turborepo (turbo.json)

Tarea	Dependencias	Cache	Uso
build	^build	Sí	Build de todas las apps
@nappai/docs#build	ninguna	Sí	Build del portal de docs
dev	—	No (persistent)	Arrancar en desarrollo
test	^build	Sí	Tests unitarios Jest
e2e	build	No	Tests Playwright
e2e:access-control	build	No	Suite crítica de acceso
lint	—	Sí	ESLint en todo el monorepo
db:migrate	—	No	Migraciones Prisma
db:studio	—	No (persistent)	Prisma Studio

Scripts raíz

pnpm dev              # Arranca web + api en paralelo
pnpm build            # Build de todas las apps
pnpm test             # Tests unitarios
pnpm e2e              # Tests Playwright completos
pnpm e2e:access-control  # Solo suite de access-control (blocking en CI)
pnpm lint             # ESLint global
pnpm db:migrate       # Aplica migraciones
pnpm db:studio        # Abre Prisma Studio
pnpm docs:dev         # Arranca el portal de docs en :4321
pnpm docs:build       # Build estático del portal de docs

Workspace packages

@nappai/shared-types

Tipos TypeScript compartidos entre web y api:

• UserRole, AccessLevel, OrgPlan — enums del dominio
• ACCESS_HIERARCHY, CONTENT_LEVEL_REQUIREMENTS — tablas de permisos
• DTOs de respuesta de la API

@nappai/shared-schemas

Schemas Zod usados para validación en api y en formularios de web:

• Son la fuente de verdad de validación — un DTO NestJS siempre tiene su schema Zod equivalente

Reglas del monorepo

1. NUNCA queries raw a BD — siempre Prisma service
2. NUNCA llamar LLMs directamente desde Fluency — todo pasa por ai-backend
3. Los schemas Zod en packages/shared-schemas son la fuente de verdad de validación
4. Antes de crear un módulo NestJS, verificar si ya existe en apps/api/src/modules/