433 lines
21 KiB
Markdown
433 lines
21 KiB
Markdown
# Arquitectura General - OrbiQuant IA
|
|
|
|
**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 4.18 + 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/)
|