876 lines
86 KiB
Markdown
876 lines
86 KiB
Markdown
# Arquitectura de Infraestructura - ERP Suite SaaS Platform
|
|
|
|
## 1. Vista General de Arquitectura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ INTERNET │
|
|
└─────────────────────────────────────────────────────────┘
|
|
│
|
|
┌─────────────────────────────────────────┼─────────────────────────────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
|
│ Cloudflare │ │ Cloudflare │ │ Cloudflare │
|
|
│ (CDN/WAF) │ │ (CDN/WAF) │ │ (CDN/WAF) │
|
|
│ Web Apps │ │ API │ │ Webhooks │
|
|
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ KUBERNETES CLUSTER │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ INGRESS CONTROLLER (nginx) │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────── NAMESPACES ───────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
|
|
│ │ │ erp-web │ │ erp-api │ │ erp-workers │ │ erp-webhooks │ │ erp-mobile │ │ │
|
|
│ │ │ │ │ │ │ │ │ │ │ │ │ │
|
|
│ │ │ React Apps │ │ NestJS API │ │ Background │ │ Stripe WH │ │ Mobile BFF │ │ │
|
|
│ │ │ (por vertical) │ │ (multi-tenant) │ │ Jobs │ │ WhatsApp WH │ │ │ │ │
|
|
│ │ │ │ │ │ │ │ │ Meta WH │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────── DATA LAYER ─────────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
|
|
│ │ │ PostgreSQL │ │ Redis │ │ RabbitMQ │ │ MinIO │ │ │
|
|
│ │ │ (Primary) │ │ Cluster │ │ (Message Q) │ │ (Object Store)│ │ │
|
|
│ │ │ │ │ │ │ │ │ │ │ │
|
|
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
|
│ Stripe │ │ Meta Cloud │ │ AI Services │
|
|
│ API │ │ API (WA) │ │ Claude/GPT │
|
|
└────────────────┘ └────────────────┘ └────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Arquitectura de Servicios
|
|
|
|
### 2.1 API Gateway / Backend for Frontend
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
│ API GATEWAY (Kong / nginx) │
|
|
├──────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Routes: │
|
|
│ ├── /api/v1/* → erp-api-service (main API) │
|
|
│ ├── /webhooks/stripe/* → webhook-service (Stripe callbacks) │
|
|
│ ├── /webhooks/whatsapp/*→ webhook-service (Meta callbacks) │
|
|
│ ├── /mobile/api/* → mobile-bff-service (mobile optimized) │
|
|
│ └── /ws/* → websocket-service (real-time) │
|
|
│ │
|
|
│ Features: │
|
|
│ ├── Rate Limiting (por tenant, por user, por IP) │
|
|
│ ├── JWT Validation │
|
|
│ ├── Request/Response Logging │
|
|
│ ├── CORS Management │
|
|
│ └── Circuit Breaker │
|
|
│ │
|
|
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2.2 Microservicios Core
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────────┐
|
|
│ CORE SERVICES │
|
|
├─────────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ erp-api-service │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ Auth │ │ Tenants │ │ Users │ │ RBAC │ │ │
|
|
│ │ │ Module │ │ Module │ │ Module │ │ Module │ │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ Billing │ │ Stripe │ │ AI Token │ │ Onboard │ │ │
|
|
│ │ │ Module │ │ Module │ │ Module │ │ Module │ │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ Vertical │ │ Vertical │ │ Vertical │ ... (módulos por │ │
|
|
│ │ │Construcción │ │ Vidrio │ │ Mecánicas │ vertical) │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ webhook-service │ │
|
|
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │
|
|
│ │ │ Stripe Handler │ │ WhatsApp Handler │ │ Generic Handler │ │ │
|
|
│ │ │ - Signature │ │ - Signature │ │ - Custom hooks │ │ │
|
|
│ │ │ - Events │ │ - Messages │ │ │ │ │
|
|
│ │ │ - Idempotency │ │ - Status │ │ │ │ │
|
|
│ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ worker-service │ │
|
|
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │
|
|
│ │ │ Billing Jobs │ │ WhatsApp Jobs │ │ Notification │ │ │
|
|
│ │ │ - Invoice gen │ │ - AI Process │ │ - Email │ │ │
|
|
│ │ │ - Usage calc │ │ - Send message │ │ - Push │ │ │
|
|
│ │ │ - Alerts │ │ - Media upload │ │ - In-app │ │ │
|
|
│ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ mobile-bff-service │ │
|
|
│ │ - Optimized payloads for mobile │ │
|
|
│ │ - Offline-friendly responses │ │
|
|
│ │ - Batch operations │ │
|
|
│ │ - Delta sync endpoints │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Arquitectura de Base de Datos
|
|
|
|
### 3.1 PostgreSQL Multi-Tenant con RLS
|
|
|
|
```sql
|
|
-- Configuración de schemas por dominio
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ POSTGRESQL DATABASE │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────┐ Schema: core_tenants │
|
|
│ │ tenants │ - Información de organizaciones │
|
|
│ │ tenant_settings │ - Configuraciones por tenant │
|
|
│ │ feature_flags │ - Features habilitadas │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ Schema: auth │
|
|
│ │ users │ - Usuarios del sistema │
|
|
│ │ sessions │ - Sesiones activas │
|
|
│ │ roles │ - Roles y permisos │
|
|
│ │ permissions │ - Permisos granulares │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ Schema: billing │
|
|
│ │ plans │ - Planes de suscripción │
|
|
│ │ subscriptions │ - Suscripciones activas │
|
|
│ │ invoices │ - Facturas generadas │
|
|
│ │ usage_records │ - Registros de uso (tokens, usuarios) │
|
|
│ │ stripe_customers│ - Mapeo Stripe Customer │
|
|
│ │ stripe_events │ - Log de webhooks Stripe │
|
|
│ │ ai_token_pkgs │ - Paquetes de tokens comprados │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ Schema: whatsapp │
|
|
│ │ business_numbers│ - Números WhatsApp Business │
|
|
│ │ contacts │ - Contactos de WA │
|
|
│ │ conversations │ - Conversaciones │
|
|
│ │ messages │ - Mensajes enviados/recibidos │
|
|
│ │ ai_actions │ - Acciones ejecutadas por IA │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ Schema: onboarding │
|
|
│ │ prospects │ - Prospectos │
|
|
│ │ projects │ - Proyectos de implementación │
|
|
│ │ tasks │ - Tareas de configuración │
|
|
│ │ quotes │ - Cotizaciones │
|
|
│ │ payments │ - Pagos de implementación │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ Schemas por Vertical (con RLS) │
|
|
│ │ construccion │ - Proyectos, contratos, avances... │
|
|
│ │ vidrio_templado │ - Órdenes, producción, instalación... │
|
|
│ │ mecanicas │ - Servicios, diagnósticos... │
|
|
│ │ retail │ - Productos, ventas, inventario... │
|
|
│ │ clinicas │ - Pacientes, citas, expedientes... │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 3.2 Row Level Security (RLS)
|
|
|
|
```sql
|
|
-- Ejemplo de política RLS para multi-tenancy
|
|
ALTER TABLE construccion.projects ENABLE ROW LEVEL SECURITY;
|
|
|
|
CREATE POLICY tenant_isolation_policy ON construccion.projects
|
|
USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
|
|
|
|
-- Función para establecer tenant en conexión
|
|
CREATE OR REPLACE FUNCTION set_tenant_context(p_tenant_id uuid)
|
|
RETURNS void AS $$
|
|
BEGIN
|
|
PERFORM set_config('app.current_tenant_id', p_tenant_id::text, false);
|
|
END;
|
|
$$ LANGUAGE plpgsql;
|
|
```
|
|
|
|
### 3.3 Estrategia de Conexiones
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ CONNECTION POOLING │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ API Service │ │ Worker Service │ │ Webhook Service│ │
|
|
│ │ Pool: 50 │ │ Pool: 20 │ │ Pool: 10 │ │
|
|
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
|
|
│ │ │ │ │
|
|
│ └───────────────────────┼───────────────────────┘ │
|
|
│ │ │
|
|
│ ┌────────▼────────┐ │
|
|
│ │ PgBouncer │ │
|
|
│ │ Pool: 200 │ │
|
|
│ │ Mode: txn │ │
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ ┌────────▼────────┐ │
|
|
│ │ PostgreSQL │ │
|
|
│ │ Primary │ │
|
|
│ │ max_conn: 300 │ │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Arquitectura de Caching
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ REDIS CLUSTER │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ DB 0: Sessions │ │
|
|
│ │ - JWT tokens │ │
|
|
│ │ - Refresh tokens │ │
|
|
│ │ - TTL: 24h │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ DB 1: API Cache │ │
|
|
│ │ - Query results │ │
|
|
│ │ - Computed values │ │
|
|
│ │ - TTL: 5min - 1h │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ DB 2: Rate Limiting │ │
|
|
│ │ - Per tenant limits │ │
|
|
│ │ - Per user limits │ │
|
|
│ │ - API call counters │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ DB 3: Token Usage │ │
|
|
│ │ - Real-time token counters │ │
|
|
│ │ - Flush to DB every 1min │ │
|
|
│ │ - Limit checks │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ DB 4: Pub/Sub │ │
|
|
│ │ - Real-time notifications │ │
|
|
│ │ - WebSocket broadcasts │ │
|
|
│ │ - Cache invalidation │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Arquitectura de Mensajería
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ RABBITMQ CLUSTER │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Exchanges: │
|
|
│ ├── billing.events (topic) │
|
|
│ │ ├── billing.invoice.created │
|
|
│ │ ├── billing.payment.succeeded │
|
|
│ │ └── billing.subscription.changed │
|
|
│ │ │
|
|
│ ├── whatsapp.events (topic) │
|
|
│ │ ├── whatsapp.message.received │
|
|
│ │ ├── whatsapp.message.sent │
|
|
│ │ └── whatsapp.status.updated │
|
|
│ │ │
|
|
│ ├── ai.events (topic) │
|
|
│ │ ├── ai.process.request │
|
|
│ │ ├── ai.process.complete │
|
|
│ │ └── ai.tokens.recorded │
|
|
│ │ │
|
|
│ └── notifications.events (topic) │
|
|
│ ├── notifications.email.send │
|
|
│ ├── notifications.push.send │
|
|
│ └── notifications.sms.send │
|
|
│ │
|
|
│ Queues: │
|
|
│ ├── billing-processor (durable, 3 consumers) │
|
|
│ ├── whatsapp-processor (durable, 5 consumers) │
|
|
│ ├── ai-processor (durable, 3 consumers) │
|
|
│ ├── email-sender (durable, 2 consumers) │
|
|
│ ├── push-sender (durable, 2 consumers) │
|
|
│ └── dead-letter-queue (for failed messages) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Flujo de Integración Stripe
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ STRIPE INTEGRATION FLOW │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ 1. CREACIÓN DE SUSCRIPCIÓN │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Frontend│────►│ API │────►│ Stripe │────►│ Stripe │ │
|
|
│ │ │ │ Service │ │ Service │ │ API │ │
|
|
│ └─────────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
|
│ │ │ │ │
|
|
│ ▼ │ │ │
|
|
│ ┌──────────┐ │ │ │
|
|
│ │ DB │◄─────────┴───────────────┘ │
|
|
│ │ (local) │ (crear subscription record) │
|
|
│ └──────────┘ │
|
|
│ │
|
|
│ 2. PROCESAMIENTO DE WEBHOOKS │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Stripe │────►│ Webhook │────►│ Verify │────►│ Process │ │
|
|
│ │ API │ │Endpoint │ │Signature│ │ Event │ │
|
|
│ └─────────┘ └─────────┘ └────┬────┘ └────┬────┘ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Check │ │ Update │ │
|
|
│ │Idempotent│ │ State │ │
|
|
│ └──────────┘ └──────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────┐ │
|
|
│ │ Publish │ │
|
|
│ │ Event │ │
|
|
│ └──────────┘ │
|
|
│ │
|
|
│ 3. ACTUALIZACIÓN DE CANTIDAD (per-seat) │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Add/Rem │────►│ Count │────►│ Update │────►│ Stripe │ │
|
|
│ │ User │ │ Users │ │Quantity │ │ API │ │
|
|
│ └─────────┘ └─────────┘ └────┬────┘ └────┬────┘ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Prorate │ │ New │ │
|
|
│ │Calculate │ │ Invoice │ │
|
|
│ └──────────┘ └──────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Flujo de WhatsApp + AI Agent
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ WHATSAPP + AI AGENT FLOW │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────┐ │
|
|
│ │ User │ │
|
|
│ │ WhatsApp │ │
|
|
│ └────┬─────┘ │
|
|
│ │ 1. Send Message │
|
|
│ ▼ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Meta │────►│ Webhook │────►│ Verify │ │
|
|
│ │ Cloud │ │ Handler │ │ Signature│ │
|
|
│ │ API │ │ │ │ │ │
|
|
│ └──────────┘ └──────────┘ └────┬─────┘ │
|
|
│ │ 2. Valid │
|
|
│ ▼ │
|
|
│ ┌──────────┐ │
|
|
│ │ Queue │ │
|
|
│ │ Message │ │
|
|
│ └────┬─────┘ │
|
|
│ │ 3. Async Process │
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────────────────────────────────────┐ │
|
|
│ │ AI PROCESSOR │ │
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
|
│ │ │ Identify │────►│ Check │────►│Determine │ │ │
|
|
│ │ │ User │ │ Perms │ │ Intent │ │ │
|
|
│ │ └──────────┘ └──────────┘ └────┬─────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ┌─────────────────────────────────┼─────────────┐ │ │
|
|
│ │ │ │ │ │ │
|
|
│ │ ▼ ▼ ▼ │ │
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
|
│ │ │ Query │ │ Create │ │ Update │ │ │
|
|
│ │ │ ERP │ │ Record │ │ Record │ │ │
|
|
│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │
|
|
│ │ │ │ │ │ │
|
|
│ │ └────────────────────────────────┼─────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌──────────┐ │ │
|
|
│ │ │ Generate │ │ │
|
|
│ │ │ Response │ │ │
|
|
│ │ │ (AI) │ │ │
|
|
│ │ └────┬─────┘ │ │
|
|
│ │ │ │ │
|
|
│ └───────────────────────────────────────┼──────────────────────┘ │
|
|
│ │ 4. Response │
|
|
│ ▼ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Record │◄────│ Send │◄────│ Track │ │
|
|
│ │ Tokens │ │ Message │ │ Usage │ │
|
|
│ └──────────┘ └────┬─────┘ └──────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────┐ │
|
|
│ │ Meta │ │
|
|
│ │ Cloud │ │
|
|
│ │ API │ │
|
|
│ └────┬─────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────┐ │
|
|
│ │ User │ │
|
|
│ │ WhatsApp │ │
|
|
│ └──────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Arquitectura Mobile
|
|
|
|
### 8.1 Estructura del Monorepo
|
|
|
|
```
|
|
apps/mobile/
|
|
├── packages/
|
|
│ ├── core/ # Paquetes compartidos
|
|
│ │ ├── api/ # Cliente API
|
|
│ │ │ ├── client.ts # Axios instance
|
|
│ │ │ ├── interceptors.ts # Auth, retry, logging
|
|
│ │ │ └── endpoints/ # Endpoints por módulo
|
|
│ │ ├── auth/ # Autenticación
|
|
│ │ │ ├── AuthContext.tsx
|
|
│ │ │ ├── useAuth.ts
|
|
│ │ │ └── tokenStorage.ts
|
|
│ │ ├── storage/ # Persistencia local
|
|
│ │ │ ├── database.ts # WatermelonDB setup
|
|
│ │ │ ├── models/ # Modelos offline
|
|
│ │ │ └── migrations/ # Migraciones DB
|
|
│ │ └── sync/ # Sincronización
|
|
│ │ ├── SyncManager.ts
|
|
│ │ ├── ConflictResolver.ts
|
|
│ │ └── DeltaSync.ts
|
|
│ │
|
|
│ ├── biometrics/ # Autenticación biométrica
|
|
│ │ ├── FacialRecognition.tsx
|
|
│ │ ├── Fingerprint.tsx
|
|
│ │ ├── LivenessDetection.ts
|
|
│ │ └── hooks/
|
|
│ │
|
|
│ ├── camera/ # Captura de fotos
|
|
│ │ ├── CameraCapture.tsx
|
|
│ │ ├── GeoTagging.ts
|
|
│ │ └── ImageCompression.ts
|
|
│ │
|
|
│ ├── notifications/ # Push notifications
|
|
│ │ ├── FCMHandler.ts
|
|
│ │ └── NotificationService.ts
|
|
│ │
|
|
│ └── ui/ # Componentes UI
|
|
│ ├── Button.tsx
|
|
│ ├── Card.tsx
|
|
│ ├── Input.tsx
|
|
│ └── theme/
|
|
│
|
|
├── apps/ # Apps por perfil
|
|
│ ├── construccion-encargado/
|
|
│ │ ├── src/
|
|
│ │ │ ├── screens/
|
|
│ │ │ │ ├── CheckIn.tsx
|
|
│ │ │ │ ├── Projects.tsx
|
|
│ │ │ │ ├── DailyReport.tsx
|
|
│ │ │ │ └── Materials.tsx
|
|
│ │ │ └── navigation/
|
|
│ │ ├── app.json
|
|
│ │ └── package.json
|
|
│ │
|
|
│ ├── construccion-almacen/
|
|
│ ├── construccion-cliente/
|
|
│ ├── vidrio-produccion/
|
|
│ ├── vidrio-instalador/
|
|
│ ├── mecanicas-tecnico/
|
|
│ └── retail-vendedor/
|
|
│
|
|
├── package.json # Workspaces config
|
|
└── turbo.json # Turborepo config
|
|
```
|
|
|
|
### 8.2 Flujo de Sincronización Offline
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ OFFLINE SYNC ARCHITECTURE │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ MOBILE APP │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ React │────►│ Zustand │────►│ WatermelonDB│ │ │
|
|
│ │ │ Component │ │ Store │ │ (SQLite) │ │ │
|
|
│ │ └─────────────┘ └──────┬──────┘ └──────┬──────┘ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ ▼ ▼ │ │
|
|
│ │ ┌──────────────────────────────┐ │ │
|
|
│ │ │ SYNC MANAGER │ │ │
|
|
│ │ │ ┌──────────┐ ┌──────────┐ │ │ │
|
|
│ │ │ │ Pending │ │ Delta │ │ │ │
|
|
│ │ │ │ Queue │ │ Tracker │ │ │ │
|
|
│ │ │ └──────────┘ └──────────┘ │ │ │
|
|
│ │ └──────────────┬───────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ └─────────────────────────────────────┼────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌─────────▼─────────┐ │
|
|
│ │ Network Status │ │
|
|
│ │ Detector │ │
|
|
│ └─────────┬─────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────────────────┴──────────────────────────────┐ │
|
|
│ │ │ │ │
|
|
│ ▼ (offline) │ (online) ▼ │ │
|
|
│ ┌──────────────┐ │ ┌──────────────┐ │
|
|
│ │ Queue Write │ │ │ Execute │ │
|
|
│ │ Operations │ │ │ Sync │ │
|
|
│ └──────────────┘ │ └──────┬───────┘ │
|
|
│ │ │ │
|
|
│ │ ▼ │
|
|
│ │ ┌──────────────────┐ │
|
|
│ │ │ 1. Push pending │ │
|
|
│ │ │ 2. Pull changes │ │
|
|
│ │ │ 3. Resolve │ │
|
|
│ │ │ conflicts │ │
|
|
│ │ │ 4. Update local │ │
|
|
│ │ └────────┬─────────┘ │
|
|
│ │ │ │
|
|
│ │ ▼ │
|
|
│ │ ┌──────────────────┐ │
|
|
│ │ │ Mobile BFF │ │
|
|
│ │ │ API │ │
|
|
│ │ └──────────────────┘ │
|
|
│ │ │
|
|
└────────────────────────────────────────┴────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Arquitectura de CI/CD
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ CI/CD PIPELINE │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ GITHUB ACTIONS │ │
|
|
│ │ │ │
|
|
│ │ on: push to main │ │
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
|
│ │ │ Lint │►│ Test │►│ Build │►│ Docker │►│ Deploy │ │ │
|
|
│ │ │ │ │ (Jest) │ │ (TypeScript)│ │ Push │ │ K8s │ │ │
|
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
|
|
│ │ │ │
|
|
│ │ on: push to develop │ │
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
|
│ │ │ Lint │►│ Test │►│ Build │►│ Deploy │ │ │
|
|
│ │ │ │ │ (Jest) │ │ │ │ Staging │ │ │
|
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ MOBILE BUILDS (EAS) │ │
|
|
│ │ │ │
|
|
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │
|
|
│ │ │ Development │ │ Preview │ │ Production │ │ │
|
|
│ │ │ - Internal │ │ - TestFlight │ │ - App Store │ │ │
|
|
│ │ │ - APK │ │ - Play Console │ │ - Play Store │ │ │
|
|
│ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ ENVIRONMENTS │ │
|
|
│ │ │ │
|
|
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ Development │ │ Staging │ │ Production │ │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ │ │ - Local K8s │ │ - GKE small │ │ - GKE prod │ │ │
|
|
│ │ │ - PostgreSQL │ │ - CloudSQL │ │ - CloudSQL │ │ │
|
|
│ │ │ local │ │ dev │ │ prod │ │ │
|
|
│ │ │ - Stripe │ │ - Stripe │ │ - Stripe │ │ │
|
|
│ │ │ test mode │ │ test mode │ │ live mode │ │ │
|
|
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Seguridad
|
|
|
|
### 10.1 Capas de Seguridad
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ SECURITY LAYERS │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Layer 1: Network │
|
|
│ ├── Cloudflare WAF (DDoS, Bot protection) │
|
|
│ ├── VPC isolation │
|
|
│ ├── Private subnets for DB │
|
|
│ └── Firewall rules (ingress/egress) │
|
|
│ │
|
|
│ Layer 2: Application │
|
|
│ ├── JWT authentication │
|
|
│ ├── API rate limiting │
|
|
│ ├── Input validation (Zod schemas) │
|
|
│ ├── SQL injection prevention (TypeORM) │
|
|
│ ├── XSS prevention (React escaping) │
|
|
│ └── CSRF tokens │
|
|
│ │
|
|
│ Layer 3: Data │
|
|
│ ├── Row Level Security (RLS) for multi-tenancy │
|
|
│ ├── Encryption at rest (PostgreSQL) │
|
|
│ ├── Encryption in transit (TLS 1.3) │
|
|
│ ├── Secrets in Vault/GCP Secret Manager │
|
|
│ └── PII masking in logs │
|
|
│ │
|
|
│ Layer 4: Compliance │
|
|
│ ├── Audit logging (todas las operaciones) │
|
|
│ ├── Data retention policies │
|
|
│ ├── GDPR/LFPDPPP compliance │
|
|
│ └── SOC2 preparedness │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 10.2 Autenticación y Autorización
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ AUTH ARCHITECTURE │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ JWT TOKEN STRUCTURE │ │
|
|
│ │ │ │
|
|
│ │ { │ │
|
|
│ │ "sub": "user_id", │ │
|
|
│ │ "tid": "tenant_id", │ │
|
|
│ │ "roles": ["admin", "operator"], │ │
|
|
│ │ "permissions": ["project:read", "project:write"], │ │
|
|
│ │ "plan": "growth", │ │
|
|
│ │ "exp": 1699999999 │ │
|
|
│ │ } │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ PERMISSION CHECK FLOW │ │
|
|
│ │ │ │
|
|
│ │ Request ──► Extract JWT ──► Validate ──► Set Tenant Context ──► │ │
|
|
│ │ │ │ │
|
|
│ │ Check Permission ◄───┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ┌─────────────┴─────────────┐ │ │
|
|
│ │ ▼ ▼ │ │
|
|
│ │ Allowed Denied │ │
|
|
│ │ │ │ │ │
|
|
│ │ ▼ ▼ │ │
|
|
│ │ Execute Handler Return 403 │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 11. Monitoreo y Observabilidad
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
|
│ OBSERVABILITY STACK │
|
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ METRICS │ │
|
|
│ │ │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
|
|
│ │ │ Prometheus │◄────│ Services │ │ Grafana │ │ │
|
|
│ │ │ │ │ /metrics │ │ │ │ │
|
|
│ │ └─────┬──────┘ └────────────┘ └─────┬──────┘ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └─────────────────────────────────────┘ │ │
|
|
│ │ │ │
|
|
│ │ Key Metrics: │ │
|
|
│ │ - Request latency (p50, p95, p99) │ │
|
|
│ │ - Error rate by endpoint │ │
|
|
│ │ - Active subscriptions │ │
|
|
│ │ - Token usage per tenant │ │
|
|
│ │ - WhatsApp message volume │ │
|
|
│ │ - Queue depth │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ LOGGING │ │
|
|
│ │ │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
|
|
│ │ │ Loki │◄────│ Promtail │◄────│ Services │ │ │
|
|
│ │ │ │ │ │ │ stdout │ │ │
|
|
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
|
|
│ │ │ │
|
|
│ │ Log Structure: │ │
|
|
│ │ { │ │
|
|
│ │ "timestamp": "...", │ │
|
|
│ │ "level": "info|warn|error", │ │
|
|
│ │ "tenant_id": "...", │ │
|
|
│ │ "user_id": "...", │ │
|
|
│ │ "request_id": "...", │ │
|
|
│ │ "message": "...", │ │
|
|
│ │ "context": {...} │ │
|
|
│ │ } │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ TRACING │ │
|
|
│ │ │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
|
|
│ │ │ Jaeger │◄────│OpenTelemetry│◄───│ Services │ │ │
|
|
│ │ │ │ │ Collector │ │ │ │ │
|
|
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ ALERTING │ │
|
|
│ │ │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
|
|
│ │ │ AlertMgr │────►│ Slack │ │ PagerDuty │ │ │
|
|
│ │ │ │────►│ │ │ │ │ │
|
|
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
|
|
│ │ │ │
|
|
│ │ Alert Rules: │ │
|
|
│ │ - Error rate > 1% for 5 min │ │
|
|
│ │ - Latency p95 > 2s for 5 min │ │
|
|
│ │ - Payment failure rate > 5% │ │
|
|
│ │ - Queue depth > 1000 for 10 min │ │
|
|
│ │ - Token usage > 90% of limit │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 12. Estimación de Infraestructura
|
|
|
|
### 12.1 Recursos por Ambiente
|
|
|
|
| Recurso | Development | Staging | Production |
|
|
|---------|-------------|---------|------------|
|
|
| K8s Nodes | 2 x n1-standard-2 | 3 x n1-standard-4 | 6 x n1-standard-8 |
|
|
| PostgreSQL | db-custom-2-4096 | db-custom-4-8192 | db-custom-8-16384 + replica |
|
|
| Redis | 1GB | 5GB | 10GB cluster |
|
|
| RabbitMQ | 1 node | 1 node | 3 node cluster |
|
|
| MinIO/GCS | 10GB | 100GB | 1TB |
|
|
|
|
### 12.2 Costo Mensual Estimado (GCP)
|
|
|
|
| Componente | Development | Staging | Production |
|
|
|------------|-------------|---------|------------|
|
|
| GKE Cluster | $100 | $300 | $1,200 |
|
|
| Cloud SQL | $50 | $200 | $600 |
|
|
| Memorystore (Redis) | $30 | $100 | $300 |
|
|
| Cloud Storage | $5 | $20 | $100 |
|
|
| Networking | $20 | $50 | $200 |
|
|
| Monitoring | $10 | $30 | $100 |
|
|
| **Total** | **$215** | **$700** | **$2,500** |
|
|
|
|
### 12.3 Costos de Terceros
|
|
|
|
| Servicio | Estimado Mensual |
|
|
|----------|------------------|
|
|
| Stripe fees | 2.9% + $0.30/txn |
|
|
| Claude API | ~$500-2,000 (según uso) |
|
|
| WhatsApp Business | $0.05-0.15/conversación |
|
|
| Firebase (Push) | $25 (Blaze plan) |
|
|
| App Store fees | $99/año |
|
|
| Play Store fees | $25 (único) |
|
|
|
|
---
|
|
|
|
## 13. Próximos Pasos de Implementación
|
|
|
|
### Sprint 22: Fundamentos Stripe
|
|
|
|
1. **Infraestructura:**
|
|
- [ ] Configurar cuenta Stripe Connect
|
|
- [ ] Crear webhook endpoint seguro
|
|
- [ ] Setup de event logging
|
|
|
|
2. **Base de Datos:**
|
|
- [ ] Crear tablas stripe_customers, stripe_events
|
|
- [ ] Índices para búsqueda rápida
|
|
|
|
3. **Backend:**
|
|
- [ ] StripeService con métodos base
|
|
- [ ] StripeWebhookController
|
|
- [ ] Signature verification middleware
|
|
|
|
4. **Testing:**
|
|
- [ ] Tests con Stripe CLI
|
|
- [ ] Webhook retry simulation
|
|
|
|
---
|
|
|
|
**Creado por:** Requirements-Analyst
|
|
**Fecha:** 2025-12-05
|
|
**Versión:** 1.0
|