AvanzaCast/ARCHITECTURE.md

AvanzaCast - Arquitectura Modular

Visión General

AvanzaCast se divide en 4 módulos principales que funcionan de forma independiente pero comunicada:

AvanzaCast/
├── packages/
│   ├── landing-page/       # Módulo público (Next.js/Vite)
│   ├── backend-api/        # API central (Node.js + Express)
│   ├── broadcast-studio/   # Studio de streaming (React + WebRTC)
│   └── admin-panel/        # Panel SaaS (React + Admin UI)
├── shared/
│   ├── types/              # TypeScript types compartidos
│   ├── utils/              # Utilidades compartidas
│   └── config/             # Configuración compartida
└── docs/
    ├── api/                # Documentación de APIs
    └── deployment/         # Guías de despliegue

Módulos

1. Landing Page (Public)

Tecnología: Next.js 15 / Vite + React Puerto: 3000 Responsabilidades:

• Marketing y presentación del producto
• Registro de nuevos usuarios
• Login y autenticación inicial
• Pricing y planes
• Blog/recursos
• SEO optimizado

Conexiones:

• → backend-api para registro/login
• → Redirección a broadcast-studio post-login
• → Redirección a admin-panel para admins

---

2. Backend API (Core)

Tecnología: Node.js + Express + TypeScript Puerto: 4000 Base de datos: PostgreSQL + Redis Responsabilidades:

• Autenticación (JWT) y autorización
• Gestión de usuarios y perfiles
• Planes de pago (Stripe/PayPal)
• Integraciones externas:
  • YouTube API
  • Facebook Graph API
  • Twitch API
  • LinkedIn API
• WebSocket para streaming en vivo
• Storage (S3/MinIO) para grabaciones
• Transcoding (FFmpeg) de videos
• Analytics y métricas

Endpoints principales:

/api/v1/auth/*          # Autenticación
/api/v1/users/*         # Gestión de usuarios
/api/v1/subscriptions/* # Planes y pagos
/api/v1/streaming/*     # Sesiones de streaming
/api/v1/integrations/*  # Conexiones a plataformas
/api/v1/media/*         # Grabaciones y assets

Conexiones:

• ← Recibe requests de todos los frontends
• → PostgreSQL para persistencia
• → Redis para cache y sesiones
• → S3/MinIO para almacenamiento
• → APIs externas (YouTube, Facebook, etc)

---

3. Broadcast Studio (App Principal)

Tecnología: React + TypeScript + WebRTC Puerto: 3001 Responsabilidades:

• Estudio virtual de streaming
• WebRTC para captura de video/audio
• Gestión de escenas y overlays
• Multistream simultáneo
• Chat en tiempo real
• Invitados y colaboración
• Controles de streaming (start/stop/pause)
• Preview en tiempo real

Características clave:

• Editor de escenas drag & drop
• Biblioteca de overlays y branding
• Monitor de calidad de stream
• Grabación local y en la nube
• Gestión de invitados (green room)

Conexiones:

• → backend-api para autenticación
• → backend-api WebSocket para streaming
• → APIs de plataformas vía backend-api

---

4. Admin Panel (SaaS Dashboard)

Tecnología: React + TypeScript + Admin UI (Ant Design/Material-UI) Puerto: 3002 Responsabilidades:

• Dashboard de métricas globales
• Gestión de usuarios:
  • CRUD de usuarios
  • Asignación de roles
  • Suspensión/activación de cuentas
• Gestión de planes de pago:
  • Crear/editar planes
  • Ver suscripciones activas
  • Historial de pagos
  • Facturación
• Configuración de plataforma:
  • Límites de streaming
  • Integraciones habilitadas
  • Configuración de storage
• Analytics y reportes:
  • Usuarios activos
  • Minutos de streaming
  • Revenue por plan
  • Uso de recursos
• Soporte:
  • Tickets de usuarios
  • Logs de errores
  • Auditoría de sistema

Roles:

• Super Admin: Acceso total
• Admin: Gestión de usuarios y contenido
• Support: Solo lectura y soporte

Conexiones:

• → backend-api con permisos de admin
• ← Solo accesible para usuarios con rol admin

---

Comunicación entre Módulos

Autenticación Compartida (JWT)

// Token JWT compartido entre módulos
interface JWTPayload {
  userId: string;
  email: string;
  role: 'user' | 'admin' | 'super_admin';
  subscription: {
    plan: 'free' | 'starter' | 'pro' | 'enterprise';
    status: 'active' | 'cancelled' | 'expired';
  };
  exp: number;
}

Flow de Autenticación

1. Usuario → Landing Page (login)
2. Landing → Backend API (/api/v1/auth/login)
3. Backend → Responde con JWT
4. Landing → Guarda JWT en localStorage
5. Landing → Redirige a Broadcast Studio con token
6. Broadcast Studio → Valida JWT con Backend
7. Broadcast Studio → Inicia sesión del usuario

Variables de Entorno por Módulo

landing-page/.env:

VITE_API_URL=http://localhost:4000
VITE_STUDIO_URL=http://localhost:3001
VITE_ADMIN_URL=http://localhost:3002

backend-api/.env:

PORT=4000
DATABASE_URL=postgresql://user:pass@localhost:5432/avanzacast
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key
STRIPE_SECRET_KEY=sk_test_...
AWS_S3_BUCKET=avanzacast-recordings

# Platform APIs
YOUTUBE_CLIENT_ID=...
YOUTUBE_CLIENT_SECRET=...
FACEBOOK_APP_ID=...
FACEBOOK_APP_SECRET=...
TWITCH_CLIENT_ID=...
TWITCH_CLIENT_SECRET=...

broadcast-studio/.env:

VITE_API_URL=http://localhost:4000
VITE_WS_URL=ws://localhost:4000

admin-panel/.env:

VITE_API_URL=http://localhost:4000

---

Stack Tecnológico Detallado

Frontend (Todos los módulos)

• Framework: React 18 + TypeScript
• Build Tool: Vite 4
• Routing: React Router v6
• State Management: Zustand / Redux Toolkit
• UI Components:
  • Landing: Tailwind CSS + HeadlessUI
  • Studio: Tailwind CSS + Custom Components
  • Admin: Ant Design / Material-UI
• HTTP Client: Axios
• WebSocket: Socket.io-client
• Forms: React Hook Form + Zod

Backend

• Runtime: Node.js 20 LTS
• Framework: Express.js
• Language: TypeScript
• ORM: Prisma / TypeORM
• Validation: Zod
• Authentication: Passport.js + JWT
• WebSocket: Socket.io
• File Upload: Multer
• Video Processing: FFmpeg

Base de datos

• Primary: PostgreSQL 15
• Cache: Redis 7
• Storage: AWS S3 / MinIO

DevOps

• Containerización: Docker + Docker Compose
• Monorepo: Turborepo / Nx
• CI/CD: GitHub Actions
• Hosting:
  • Frontend: Vercel / Netlify
  • Backend: Railway / Render / AWS EC2
  • DB: Railway / AWS RDS

---

Próximos Pasos de Implementación

1. ✅ Crear estructura de carpetas
2. ⏳ Configurar monorepo (Turborepo)
3. ⏳ Migrar landing actual a packages/landing-page
4. ⏳ Crear backend-api base con Express + TypeScript
5. ⏳ Configurar base de datos (Prisma + PostgreSQL)
6. ⏳ Implementar autenticación JWT
7. ⏳ Crear broadcast-studio base
8. ⏳ Crear admin-panel base
9. ⏳ Configurar comunicación entre módulos
10. ⏳ Implementar integraciones con plataformas

---

Estructura de Desarrollo

# Instalar dependencias de todos los módulos
npm install

# Desarrollo (todos los módulos)
npm run dev

# Desarrollo individual
npm run dev:landing
npm run dev:api
npm run dev:studio
npm run dev:admin

# Build de producción
npm run build

# Tests
npm run test

---

Fecha: 3 de noviembre de 2025 Versión: 1.0.0 Estado: En diseño