inmobiliaria-analytics/docs/97-adr/ADR-001-stack-tecnologico.md

---
id: "ADR-001"
title: "Seleccion de Stack Tecnologico"
type: "Architecture Decision Record"
status: "Accepted"
date: "2026-01-04"
deciders: ["Tech Lead", "Backend Team", "Frontend Team"]
tags: ["stack", "nestjs", "react", "postgresql"]
---

# ADR-001: Seleccion de Stack Tecnologico

**Status:** Accepted
**Date:** 2026-01-04
**Deciders:** Tech Lead, Backend Team, Frontend Team
**Tags:** stack, nestjs, react, postgresql

---

## Context

El proyecto Inmobiliaria Analytics requiere un stack tecnologico que soporte:

1. **Alto rendimiento en analytics**: Procesamiento eficiente de grandes volumenes de datos inmobiliarios
2. **Escalabilidad horizontal**: Crecimiento de usuarios y datos sin rediseno
3. **Time-to-market rapido**: MVP en Q1 2026
4. **Mantenibilidad a largo plazo**: Codigo limpio y documentado
5. **Ecosistema maduro**: Librerias y comunidad activa

### Restricciones

- Equipo con experiencia en TypeScript/JavaScript
- Infraestructura existente basada en Docker
- Base de datos relacional requerida para transacciones
- Compatibilidad con sistema NEXUS existente

---

## Decision

Seleccionamos el siguiente stack tecnologico:

### Backend: NestJS 10.x + TypeORM

**Razon:** Framework TypeScript-first con arquitectura modular que facilita el desarrollo de APIs escalables. TypeORM proporciona un ORM robusto con soporte para migraciones.

### Frontend: React 18.x + TypeScript + Vite

**Razon:** Ecosistema maduro con excelente soporte para aplicaciones de datos. Vite proporciona DX rapida. TypeScript asegura type-safety end-to-end.

### Base de Datos: PostgreSQL 16 + Redis 7

**Razon:** PostgreSQL ofrece:
- Extensiones geograficas (PostGIS) para datos inmobiliarios
- JSONB para datos semi-estructurados
- Excelente rendimiento en queries analiticas
- ACID compliance

Redis para:
- Caching de queries frecuentes
- Sesiones de usuario
- Rate limiting

### Autenticacion: Passport + JWT

**Razon:** Estrategia stateless que facilita escalabilidad horizontal. JWT permite validacion sin consulta a BD.

---

## Alternatives Considered

### Alternative 1: Python + FastAPI + SQLAlchemy

**Pros:**
- Excelente para ML/Analytics
- Librerias de data science maduras
- FastAPI es muy rapido

**Cons:**
- Equipo tiene menos experiencia
- Dos stacks de lenguaje (Python + JS/TS para frontend)
- Menor integracion con ecosistema existente

**Decision:** Rechazada - curva de aprendizaje y fragmentacion de stack

### Alternative 2: Next.js Full-Stack

**Pros:**
- Un solo framework
- SSR built-in
- Vercel deployment simple

**Cons:**
- Menos flexible para APIs complejas
- Acoplamiento frontend-backend
- Escalabilidad de API limitada

**Decision:** Rechazada - requerimos separacion clara para escalabilidad independiente

### Alternative 3: Go + Fiber + React

**Pros:**
- Alto rendimiento
- Compilacion a binarios
- Excelente para microservicios

**Cons:**
- Cambio significativo de paradigma
- Menos ecosistema para web apps
- Curva de aprendizaje alta

**Decision:** Rechazada - time-to-market afectado significativamente

### Alternative 4: MongoDB en lugar de PostgreSQL

**Pros:**
- Flexibilidad de schema
- JSON nativo
- Facil escalabilidad horizontal

**Cons:**
- Sin transacciones ACID robustas (hasta recientemente)
- Datos inmobiliarios son relacionales por naturaleza
- PostGIS superior para geo-datos

**Decision:** Rechazada - PostgreSQL mejor para dominio inmobiliario

---

## Consequences

### Positivas

1. **Consistencia de lenguaje**: TypeScript end-to-end
2. **Reutilizacion**: DTOs y tipos compartidos
3. **Productividad**: Equipo productivo desde dia 1
4. **Escalabilidad**: Cada componente escala independientemente
5. **Comunidad**: Amplio soporte y recursos

### Negativas

1. **Node.js single-threaded**: Puede ser limitante para CPU-intensive
   - Mitigacion: Worker threads o microservicio Python para ML
2. **ORM overhead**: TypeORM puede ser lento para queries complejas
   - Mitigacion: Raw queries para analytics criticos
3. **Bundle size React**: Apps grandes pueden ser pesadas
   - Mitigacion: Code splitting, lazy loading

### Neutrales

1. Requiere setup inicial de TypeORM migrations
2. Configuracion de Swagger para documentacion API
3. Setup de testing con Jest

---

## Implementation Notes

### Dependencias Clave

```json
{
  "backend": {
    "@nestjs/core": "^10.3.0",
    "@nestjs/typeorm": "^10.0.1",
    "typeorm": "^0.3.19",
    "pg": "^8.11.3"
  },
  "frontend": {
    "react": "^18.x",
    "typescript": "^5.3.x",
    "vite": "^5.x"
  }
}
```

### Configuracion Inicial

1. Monorepo con apps separadas
2. Docker Compose para desarrollo local
3. GitHub Actions para CI/CD
4. PostgreSQL con schemas por dominio

---

## References

- [NestJS Documentation](https://docs.nestjs.com/)
- [TypeORM Documentation](https://typeorm.io/)
- [React Documentation](https://react.dev/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [STACK-TECNOLOGICO.md](../00-vision-general/STACK-TECNOLOGICO.md)

---

## Status History

| Date | Status | Notes |
|------|--------|-------|
| 2026-01-04 | Proposed | ADR creado |
| 2026-01-04 | Accepted | Aprobado por equipo tecnico |

---

**Document:** ADR-001
**Status:** Accepted
**Date Created:** 2026-01-04
**Supersedes:** N/A