--- id: "ARQUITECTURA-GENERAL" title: "Arquitectura General - Trading Platform" type: "Documentation" project: "trading-platform" version: "1.0.0" updated_date: "2026-02-06" --- # Arquitectura General - Trading Platform **Version:** 1.0.0 **Fecha:** 2025-12-05 **Estado:** Aprobado **ADR Relacionado:** [ADR-002](../97-adr/ADR-002-arquitectura-monorepo.md) --- ## Vista de Alto Nivel ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ CLIENTES │ ├─────────────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Web App │ │ Mobile App │ │ Admin Panel│ │ │ │ (React) │ │(React Native│ │ (React) │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ └──────────┼──────────────────┼──────────────────┼────────────────────────┘ │ │ │ └──────────────────┼──────────────────┘ │ HTTPS ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ API GATEWAY │ │ (Express.js + Rate Limiting) │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ /api/v1/auth /api/v1/education /api/v1/trading ... │ │ │ └───────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────┬───────────────────────────────────────────┘ │ ┌──────────────────┼──────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ BACKEND API │ │ ML ENGINE │ │ EXTERNAL APIs │ │ (Express.js) │ │ (FastAPI) │ │ │ │ │ │ │ │ - Stripe │ │ - Auth Module │ │ - Predictions │ │ - Twilio │ │ - Education │ │ - Signals │ │ - Market Data │ │ - Trading │ │ - Training │ │ - OAuth │ │ - Investment │ │ │ │ │ │ - Payments │ │ │ │ │ │ - Admin │ │ │ │ │ └────────┬────────┘ └────────┬────────┘ └─────────────────┘ │ │ │ │ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ DATA LAYER │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ PostgreSQL │ │ Redis │ │ File Storage │ │ │ │ (7 schemas) │ │ (Cache) │ │ (S3/Minio) │ │ │ │ │ │ │ │ │ │ │ │ - public │ │ - Sessions │ │ - Documents │ │ │ │ - education │ │ - Rate limits │ │ - Avatars │ │ │ │ - trading │ │ - ML cache │ │ - Courses │ │ │ │ - investment │ │ - Real-time │ │ - Exports │ │ │ │ - financial │ │ │ │ │ │ │ │ - ml │ │ │ │ │ │ │ │ - audit │ │ │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## Arquitectura por Capas ### 1. Capa de Presentacion (Frontend) ``` apps/frontend/ ├── src/ │ ├── components/ # Componentes reutilizables │ │ ├── common/ # Buttons, inputs, modals │ │ ├── layout/ # MainLayout, AuthLayout │ │ └── charts/ # Trading charts │ │ │ ├── modules/ # Feature modules │ │ ├── auth/ # Login, Register, OAuth │ │ ├── dashboard/ # Dashboard principal │ │ ├── education/ # Cursos, lecciones │ │ ├── trading/ # Charts, signals │ │ ├── investment/ # Cuentas, agentes │ │ └── settings/ # Configuracion │ │ │ ├── stores/ # Zustand stores │ ├── hooks/ # Custom hooks │ ├── services/ # API clients │ └── utils/ # Helpers ``` **Tecnologias:** - React 18 + TypeScript - Vite (bundler) - TanStack Query (data fetching) - Zustand (state management) - Tailwind CSS (styling) - Lightweight Charts (trading charts) ### 2. Capa de Aplicacion (Backend API) ``` apps/backend/ ├── src/ │ ├── modules/ # Domain modules │ │ ├── auth/ # Autenticacion │ │ │ ├── controllers/ │ │ │ ├── services/ │ │ │ ├── types/ │ │ │ └── validators/ │ │ ├── education/ # Cursos │ │ ├── trading/ # Trading │ │ ├── investment/ # Inversiones │ │ ├── payments/ # Pagos │ │ └── admin/ # Administracion │ │ │ ├── core/ # Cross-cutting │ │ ├── middleware/ # Auth, rate-limit, error │ │ ├── guards/ # Role guards │ │ └── decorators/ # Custom decorators │ │ │ ├── shared/ # Shared utilities │ │ ├── database/ # DB connection │ │ └── utils/ # Logger, helpers │ │ │ └── config/ # Configuration ``` **Tecnologias:** - Express.js 5.0.1 + TypeScript - PostgreSQL (pg driver) - Redis (caching) - JWT (auth) - Zod (validation) ### 3. Capa de ML (ML Engine) ``` apps/ml-engine/ ├── src/ │ ├── models/ # ML Models │ │ ├── range_predictor.py │ │ ├── tp_sl_classifier.py │ │ └── signal_generator.py │ │ │ ├── data/ # Data processing │ │ ├── features.py │ │ ├── targets.py │ │ └── indicators.py │ │ │ ├── api/ # FastAPI endpoints │ │ └── main.py │ │ │ └── training/ # Training pipelines │ ├── walk_forward.py │ └── hyperparameter.py │ ├── config/ # Model configs └── notebooks/ # Jupyter notebooks ``` **Tecnologias:** - Python 3.11+ - FastAPI - XGBoost - Pandas, NumPy - Scikit-learn ### 4. Capa de Datos ``` apps/database/ ├── schemas/ │ ├── 00_init_schemas.sql # Extensions, types │ ├── 01_public_schema.sql # Users, profiles │ ├── 01b_oauth_providers.sql # OAuth accounts │ ├── 02_education_schema.sql # Courses, lessons │ ├── 03_trading_schema.sql # Bots, signals │ ├── 04_investment_schema.sql # Accounts, products │ ├── 05_financial_schema.sql # Subscriptions, wallets │ ├── 06_ml_schema.sql # Models, predictions │ └── 07_audit_schema.sql # Audit logs │ ├── migrations/ # Migraciones ├── seeds/ # Datos iniciales └── scripts/ # Utilidades ``` --- ## Patrones de Arquitectura ### 1. Modular Monolith El backend sigue un patron de **monolito modular**, donde cada dominio es un modulo independiente pero desplegado como una sola unidad. ``` Ventajas: ✅ Simplicidad de despliegue ✅ Transacciones ACID nativas ✅ Facil debugging ✅ Bajo overhead de red Desventajas: ❌ Escalado vertical limitado ❌ Single point of failure ``` ### 2. Repository Pattern Separacion entre logica de negocio y acceso a datos. ```typescript // Service (logica de negocio) class UserService { constructor(private userRepo: UserRepository) {} async findByEmail(email: string) { return this.userRepo.findByEmail(email); } } // Repository (acceso a datos) class UserRepository { async findByEmail(email: string) { return db.query('SELECT * FROM users WHERE email = $1', [email]); } } ``` ### 3. Feature Modules (Frontend) Cada feature es auto-contenido con sus propios componentes, stores y servicios. ``` modules/education/ ├── pages/ # Paginas del modulo ├── components/ # Componentes especificos ├── hooks/ # Hooks del modulo ├── services/ # API calls └── store/ # Estado local ``` --- ## Flujos de Datos ### Autenticacion (OAuth) ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Client │────▶│ Backend │────▶│ OAuth │────▶│ Provider │ │ │ │ API │ │ Service │ │ (Google) │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ 1. Click │ │ │ │ "Login with │ │ │ │ Google" │ │ │ │───────────────▶│ 2. Get │ │ │ │ Auth URL │ │ │ │───────────────▶│ │ │ │ │ 3. Generate │ │ │◀───────────────│ URL │ │◀───────────────│ 4. Return URL │ │ │ │ │ │ │ 5. Redirect │ │ │ │ to Google │ │ │ │───────────────────────────────────────────────▶│ │ │ │ │ │◀──────────────────────────────────────────────│ │ 6. Callback │ │ 7. User │ │ with code │ │ approved │ │───────────────▶│ │ │ │ │ 8. Exchange │ │ │ │ code for │ │ │ │ tokens │ │ │ │───────────────▶│◀──────────────│ │ │ │ │ │ │ 9. Create/ │ │ │ │ Update user │ │ │ │ │ │ │◀───────────────│ 10. JWT tokens │ │ │ │ │ │ ``` ### Trading Signal Flow ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Market │────▶│ ML │────▶│ Backend │────▶│ Client │ │ Data │ │ Engine │ │ API │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ 1. OHLCV │ │ │ │ Real-time │ │ │ │───────────────▶│ │ │ │ │ 2. Feature │ │ │ │ Engineering │ │ │ │ │ │ │ │ 3. Predict │ │ │ │ ΔHigh/ΔLow │ │ │ │ │ │ │ │ 4. Generate │ │ │ │ Signal │ │ │ │───────────────▶│ │ │ │ │ 5. Store │ │ │ │ Signal │ │ │ │ │ │ │ │ 6. Notify │ │ │ │ via WebSocket │ │ │ │───────────────▶│ │ │ │ │ ``` --- ## Seguridad ### Capas de Seguridad ``` ┌─────────────────────────────────────────────────────────────┐ │ CAPA 1: PERIMETRO │ │ - Rate Limiting (100 req/min general, 5 req/15min auth) │ │ - WAF (Web Application Firewall) │ │ - DDoS Protection │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ CAPA 2: AUTENTICACION │ │ - JWT (access: 15min, refresh: 7d) │ │ - OAuth 2.0 (Google, Facebook, X, Apple, GitHub) │ │ - 2FA (TOTP + backup codes) │ │ - Phone verification (SMS/WhatsApp) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ CAPA 3: AUTORIZACION │ │ - RBAC (Role-Based Access Control) │ │ - RLS (Row Level Security en PostgreSQL) │ │ - API scopes por plan de suscripcion │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ CAPA 4: DATOS │ │ - Encryption at rest (PostgreSQL) │ │ - Encryption in transit (TLS 1.3) │ │ - PII encryption (passwords bcrypt) │ │ - Audit logging │ └─────────────────────────────────────────────────────────────┘ ``` ### Roles del Sistema | Rol | Descripcion | Permisos | |-----|-------------|----------| | `investor` | Usuario basico | Ver cursos, trading, invertir | | `trader` | Usuario avanzado | + Crear bots, signals | | `student` | Solo educacion | Solo modulo educativo | | `admin` | Administrador | Gestion de usuarios, contenido | | `superadmin` | Super admin | Todo + configuracion sistema | --- ## Escalabilidad ### Estrategia de Escalado ``` Fase 1 (MVP): Single Server ├── 1x Backend API ├── 1x ML Engine ├── 1x PostgreSQL └── 1x Redis Fase 2 (Growth): Horizontal ├── 3x Backend API (load balanced) ├── 2x ML Engine ├── 1x PostgreSQL (read replicas) └── 3x Redis (cluster) Fase 3 (Enterprise): Multi-region ├── Backend API (auto-scaling) ├── ML Engine (GPU cluster) ├── PostgreSQL (multi-region) └── Redis (geo-distributed) ``` --- ## Monitoreo ### Metricas Clave | Categoria | Metricas | |-----------|----------| | **Performance** | Response time, throughput, error rate | | **Business** | DAU, MAU, conversion, churn | | **ML** | Prediction accuracy, latency, drift | | **Infrastructure** | CPU, memory, disk, network | ### Stack de Observabilidad ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Logging │ │ Metrics │ │ Tracing │ │ (Winston/Pino) │ │ (Prometheus) │ │ (OpenTelemetry│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │ │ └────────────────────┼────────────────────┘ │ ▼ ┌─────────────────┐ │ Grafana │ │ Dashboards │ └─────────────────┘ ``` --- ## Referencias - [ADR-001: Stack Tecnologico](../97-adr/ADR-001-stack-tecnologico.md) - [ADR-002: Arquitectura Monorepo](../97-adr/ADR-002-arquitectura-monorepo.md) - [Stack Tecnologico](./STACK-TECNOLOGICO.md) - [Database Design](../95-guias-desarrollo/database/)