Visión General de Arquitectura
NappAI Fluency es una academia online de IA construida como monorepo. El sistema está compuesto por tres apps productivas y un motor de IA propio que se integra como microservicio.
Diagrama de Contexto (C4 Nivel 1)
Section titled “Diagrama de Contexto (C4 Nivel 1)”C4Context title NappAI Fluency — Contexto del sistema Person(user, "Usuario", "Free / Starter / Pro / Elite / Corporate") Person(admin, "Admin / Creator", "CONTENT_ADMIN, SUPER_ADMIN") System(fluency, "NappAI Fluency", "Academia online de IA — web + API + AI Backend") System_Ext(stripe, "Stripe", "Pagos y suscripciones") System_Ext(aibackend, "AI Backend", "Motor de IA propio (ADR-010)") System_Ext(bunny, "Bunny.net", "CDN de video") System_Ext(r2, "Cloudflare R2", "Almacenamiento de archivos") System_Ext(resend, "Resend", "Email transaccional") System_Ext(neon, "Neon PostgreSQL", "Base de datos serverless") Rel(user, fluency, "Usa", "HTTPS") Rel(admin, fluency, "Administra", "HTTPS") Rel(fluency, stripe, "Procesa pagos", "API REST") Rel(fluency, aibackend, "Llama al motor IA", "HTTP interno") Rel(fluency, bunny, "Sirve video", "CDN") Rel(fluency, r2, "Sube/descarga archivos", "S3 API") Rel(fluency, resend, "Envía emails", "API REST") Rel(fluency, neon, "Persiste datos", "Prisma/TCP")Diagrama de Contenedores (C4 Nivel 2)
Section titled “Diagrama de Contenedores (C4 Nivel 2)”C4Container title NappAI Fluency — Contenedores Person(user, "Usuario")
Container(web, "apps/web", "React 19 + Vite + TS", "SPA servida desde Vercel") Container(api, "apps/api", "NestJS 11 + Prisma", "API REST en Railway/Vercel") Container(aibackend, "apps/ai-backend", "NestJS 11", "Motor IA — puerto 3001") ContainerDb(db, "Neon PostgreSQL", "PostgreSQL 16", "BD serverless con pooling") ContainerDb(redis, "Upstash Redis", "Redis", "Caché + BullMQ + pub/sub")
Rel(user, web, "Navega", "HTTPS") Rel(web, api, "Llama", "REST / JSON") Rel(api, aibackend, "Solicita IA", "HTTP interno + AIBACKEND_API_KEY") Rel(api, db, "Lee/Escribe", "Prisma") Rel(api, redis, "Caché / Colas", "ioredis") Rel(aibackend, redis, "Pub/sub métricas", "ioredis")Stack Tecnológico
Section titled “Stack Tecnológico”| Capa | Tecnología | Versión | Notas |
|---|---|---|---|
| Frontend | React | 19 | Con concurrent features |
| Frontend | Vite | 6 | Build y HMR |
| Frontend | TypeScript | ~5.6 | Strict mode |
| Frontend | MUI | v7 | Componentes UI |
| Frontend | Tailwind CSS | v4 | Utility classes |
| Frontend | Redux Toolkit | latest | Store global |
| Frontend | RTK Query | latest | Data fetching |
| Frontend | React Router DOM | v7 | Routing |
| Backend | NestJS | 11 | Framework API |
| Backend | TypeScript | ~5.6 | Strict mode |
| Backend | Prisma | 6 | ORM |
| Backend | PostgreSQL | 16 | Neon Serverless |
| Backend | BullMQ | latest | Colas de tareas |
| Backend | Upstash Redis | latest | Caché + pub/sub |
| E2E | Playwright | 1.50+ | Tests bloqueantes en CI |
| Monorepo | Turborepo | v2 | Build cache incremental |
| Monorepo | pnpm | v9 | Package manager |
| Deploy FE | Vercel | — | Edge network |
| Deploy BE | Railway | — | Containers |
| Storage | Cloudflare R2 | — | S3-compatible |
| Video CDN | Bunny.net | — | Stream + CDN |
| Resend | — | Transaccional | |
| Pagos | Stripe | — | Suscripciones + webhooks |
| Monitoreo | Sentry | — | Error tracking |
| Analytics | PostHog | — | Producto analytics |
Decisiones Arquitectónicas (ADRs)
Section titled “Decisiones Arquitectónicas (ADRs)”Ver decisiones.mdx para el registro completo.
| ADR | Decisión | Estado |
|---|---|---|
| ADR-001 | Monorepo con Turborepo + pnpm | ✅ Implementado |
| ADR-010 | AI Backend como microservicio propio | ✅ Implementado |
| ADR-011 | Multi-portal frontend (Creator Studio) | ✅ Implementado |
| ADR-012 | Guide Quality Module con versionado snapshot | ✅ Implementado |