workspace/projects/trading-platform/docs/99-analisis/DECISIONES-ARQUITECTONICAS.md

# DECISIONES ARQUITECTÓNICAS - OrbiQuant IA

**Fecha:** 2025-12-06
**Estado:** Aprobado
**Versión:** 1.0.0

---

## Resumen de Decisiones

Este documento consolida las decisiones arquitectónicas tomadas para resolver los conflictos identificados en el análisis de requisitos.

---

## DEC-001: Moneda Principal

### Contexto
Se detectó conflicto entre documentos que definían planes en USD ($19-99) vs MXN (499-999).

### Decisión
**Moneda principal: USD** con soporte para conversión a MXN.

### Justificación
- Plataforma internacional de trading requiere estándar USD
- Stripe maneja mejor USD como moneda base
- MXN se soporta mediante conversión en checkout

### Implementación
```yaml
Planes (USD):
  - Basic: $19/mes
  - Pro: $49/mes
  - Premium: $99/mes

Tabla currency_exchange_rates:
  - Actualización diaria de tipo de cambio
  - Mostrar precio en MXN en UI para usuarios mexicanos
```

---

## DEC-002: Fusión/Delimitación OQI-004 y OQI-008

### Contexto
Se detectó 70-85% de duplicación funcional entre:
- OQI-004: Cuentas de Inversión PAMM
- OQI-008: Portfolio Manager

### Decisión
**Delimitar responsabilidades** (no fusionar):

| Épica | Responsabilidad Exclusiva |
|-------|---------------------------|
| OQI-004 | Cuentas PAMM gestionadas por agentes (Atlas, Orion, Nova) |
| OQI-008 | Portfolio personal del usuario, cuestionario de riesgo, metas |

### Componentes Compartidos (en `financial` schema)
- Wallets unificadas
- Historial de transacciones
- Perfil de riesgo (calculado por cuestionario de OQI-008, usado por OQI-004)

### Implementación
- OQI-004 usa `investment` schema para PAMM específico
- OQI-008 funcionalidad de portfolio se integra en dashboard general
- Cuestionario de riesgo en `investment.risk_questionnaire`
- Perfil resultante alimenta selección de agente en PAMM

---

## DEC-003: Schema de Usuarios

### Contexto
Inconsistencia entre `public.users` y `auth.users` en referencias.

### Decisión
**Schema dedicado: `auth`** para todas las tablas de autenticación.

### Justificación
- Separación de concerns clara
- Facilita RLS (Row Level Security)
- Permite migración futura a servicio de auth separado

### Implementación
```sql
-- Schema auth contiene:
auth.users
auth.user_profiles
auth.oauth_accounts
auth.sessions
auth.email_verifications
auth.phone_verifications
auth.password_reset_tokens
auth.auth_logs
auth.login_attempts
auth.rate_limiting_config

-- Todas las FK de otros schemas referencian:
REFERENCES auth.users(id)
```

---

## DEC-004: Vector Database para LLM

### Contexto
OQI-007 (LLM Agent) requiere RAG/Vector Store pero no estaba especificado.

### Decisión
**pgvector** (extensión de PostgreSQL)

### Justificación
- No requiere infraestructura adicional
- Integración nativa con PostgreSQL existente
- Suficiente para volumen inicial (< 1M embeddings)
- Migración a Pinecone/Weaviate si escala necesario

### Implementación
```sql
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE llm.embeddings (
  id UUID PRIMARY KEY,
  content_type VARCHAR(50),  -- 'lesson', 'article', 'faq'
  content_id UUID,
  embedding vector(1536),    -- OpenAI ada-002
  metadata JSONB,
  created_at TIMESTAMPTZ
);

CREATE INDEX idx_embeddings_vector ON llm.embeddings
  USING ivfflat (embedding vector_cosine_ops);
```

---

## DEC-005: Distribución PAMM

### Contexto
Ambigüedad sobre frecuencia de distribución de ganancias (80/20): ¿mensual o trimestral?

### Decisión
**Distribución mensual** con opción de reinversión.

### Justificación
- Mayor transparencia para inversionistas
- Alineado con ciclo de billing (suscripciones mensuales)
- Reinversión automática disponible para compounding

### Implementación
```sql
CREATE TYPE investment.distribution_frequency AS ENUM (
  'monthly',
  'quarterly'
);

-- Default: monthly
-- Usuario puede optar por quarterly con bonus de 2% extra
```

---

## DEC-006: Resolución de Dependencia Circular

### Contexto
OQI-003 (Trading) ↔ OQI-006 (ML Signals) tenían dependencia circular que bloqueaba MVP.

### Decisión
**Interfaz abstracta `trading.signals`** como punto de integración.

### Justificación
- Desacopla ambos módulos
- Trading puede desarrollarse con MockSignalProvider
- ML puede desarrollarse independientemente
- Integración mediante tabla compartida

### Implementación
```
trading.signals (tabla interfaz)
    ↑                    ↑
    │                    │
OQI-003             OQI-006
(consume)           (produce)
```

```sql
-- OQI-003 lee de trading.signals
-- OQI-006 escribe a trading.signals
-- No hay FK directa entre módulos
```

---

## DEC-007: Timestamps Estándar

### Contexto
Inconsistencia entre TIMESTAMP y TIMESTAMPTZ en definiciones.

### Decisión
**TIMESTAMPTZ en todas las columnas de fecha/hora**

### Justificación
- Plataforma internacional requiere timezone awareness
- PostgreSQL best practice
- Evita bugs de conversión de zonas horarias

### Implementación
```sql
-- SIEMPRE usar:
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()

-- NUNCA usar:
created_at TIMESTAMP  -- SIN timezone
```

---

## Matriz de Impacto

| Decisión | Épicas Impactadas | Archivos a Modificar |
|----------|-------------------|---------------------|
| DEC-001 | OQI-005 | ET-PAY-*.md, DDL financial |
| DEC-002 | OQI-004, OQI-008 | README.md de ambas, DDL investment |
| DEC-003 | TODAS | Todos los ET-*-database.md |
| DEC-004 | OQI-007 | ET-LLM-*.md, DDL llm |
| DEC-005 | OQI-004 | ET-INV-*.md, DDL investment |
| DEC-006 | OQI-003, OQI-006 | ET-TRD-*.md, ET-ML-*.md, DDL trading |
| DEC-007 | TODAS | Todos los DDL |

---

## Próximos Pasos

1. ✅ Documentar decisiones (este documento)
2. ✅ Crear ADRs formales (ADR-002 a ADR-006)
3. ✅ Actualizar DDLs según decisiones
4. ⏳ Actualizar especificaciones técnicas
5. ⏳ Validar con recreación de BD

---

*Documento generado por Requirements-Analyst Agent*
*OrbiQuant IA - Trading Platform*