# 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/)
