rckrdmrd
ea1879f4ad
- Configure workspace Git repository with comprehensive .gitignore - Add Odoo as submodule for ERP reference code - Include documentation: SETUP.md, GIT-STRUCTURE.md - Add gitignore templates for projects (backend, frontend, database) - Structure supports independent repos per project/subproject level Workspace includes: - core/ - Reusable patterns, modules, orchestration system - projects/ - Active projects (erp-suite, gamilit, trading-platform, etc.) - knowledge-base/ - Reference code and patterns (includes Odoo submodule) - devtools/ - Development tools and templates - customers/ - Client implementations template 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
86 KiB
86 KiB
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
-- 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)
-- 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
-
Infraestructura:
- Configurar cuenta Stripe Connect
- Crear webhook endpoint seguro
- Setup de event logging
-
Base de Datos:
- Crear tablas stripe_customers, stripe_events
- Índices para búsqueda rápida
-
Backend:
- StripeService con métodos base
- StripeWebhookController
- Signature verification middleware
-
Testing:
- Tests con Stripe CLI
- Webhook retry simulation
Creado por: Requirements-Analyst Fecha: 2025-12-05 Versión: 1.0