# 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)
```typescript
// 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**:
```bash
VITE_API_URL=http://localhost:4000
VITE_STUDIO_URL=http://localhost:3001
VITE_ADMIN_URL=http://localhost:3002
```

**backend-api/.env**:
```bash
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**:
```bash
VITE_API_URL=http://localhost:4000
VITE_WS_URL=ws://localhost:4000
```

**admin-panel/.env**:
```bash
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

```bash
# 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