---
id: "ARCH-IA"
title: "Arquitectura General - Inmobiliaria Analytics"
type: "Architecture Document"
version: "1.0.0"
status: "Draft"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# Arquitectura General - Inmobiliaria Analytics

---

## Vision Arquitectonica

Arquitectura basada en microservicios con separacion clara entre frontend, backend y datos, optimizada para analytics de alto rendimiento.

---

## Diagrama de Alto Nivel

```
                    +------------------+
                    |   Load Balancer  |
                    |     (Traefik)    |
                    +--------+---------+
                             |
           +-----------------+-----------------+
           |                                   |
+----------v----------+            +-----------v-----------+
|      Frontend       |            |       Backend         |
|    React + Vite     |            |       NestJS          |
|    Puerto: 3100     |            |    Puerto: 3101       |
+----------+----------+            +-----------+-----------+
           |                                   |
           |                    +--------------+--------------+
           |                    |              |              |
           |           +--------v----+  +------v------+  +----v-----+
           |           |    Auth     |  | Properties  |  | Analytics|
           |           |   Module    |  |   Module    |  |  Module  |
           |           +--------+----+  +------+------+  +----+-----+
           |                    |              |              |
           |                    +--------------+--------------+
           |                                   |
           |                    +--------------v--------------+
           |                    |        PostgreSQL           |
           +--------------------+        Puerto: 5439          |
                                |   Schemas: public,          |
                                |   properties, analytics     |
                                +-----------------------------+
                                              |
                                +-------------v-------------+
                                |          Redis            |
                                |      Puerto: 6386         |
                                |   Cache + Sessions        |
                                +---------------------------+
```

---

## Capas de la Arquitectura

### 1. Capa de Presentacion (Frontend)

| Componente | Tecnologia | Proposito |
|------------|------------|-----------|
| SPA | React 18.x | Interfaz de usuario |
| Build | Vite | Bundling y desarrollo |
| Estado | Zustand | Manejo de estado global |
| UI Kit | Tailwind CSS | Estilos |
| Charts | Recharts | Visualizaciones |

### 2. Capa de Aplicacion (Backend)

| Componente | Tecnologia | Proposito |
|------------|------------|-----------|
| API Server | NestJS 10.x | Framework HTTP |
| ORM | TypeORM 0.3.x | Acceso a datos |
| Auth | Passport + JWT | Autenticacion |
| Validation | class-validator | Validacion de DTOs |
| Docs | Swagger/OpenAPI | Documentacion API |

### 3. Capa de Datos

| Componente | Tecnologia | Proposito |
|------------|------------|-----------|
| RDBMS | PostgreSQL 16 | Datos principales |
| Cache | Redis 7 | Caching y sesiones |
| Search | (Futuro) Elasticsearch | Busqueda avanzada |

---

## Modulos del Sistema

### IA-001: Fundamentos

```
src/modules/
├── auth/           # Autenticacion y autorizacion
│   ├── auth.module.ts
│   ├── auth.service.ts
│   ├── auth.controller.ts
│   ├── strategies/
│   │   ├── jwt.strategy.ts
│   │   └── local.strategy.ts
│   └── guards/
│       └── jwt-auth.guard.ts
└── users/          # Gestion de usuarios
    ├── users.module.ts
    ├── users.service.ts
    └── entities/
        └── user.entity.ts
```

### IA-002: Propiedades (Planificado)

```
src/modules/
├── properties/     # CRUD de propiedades
├── locations/      # Ubicaciones geograficas
└── valuations/     # Valuaciones
```

### IA-003: Analytics (Planificado)

```
src/modules/
├── analytics/      # Motor de analytics
├── reports/        # Generacion de reportes
└── dashboards/     # Configuracion de dashboards
```

---

## Esquemas de Base de Datos

### Schema: public

Tablas de sistema y usuarios:
- `users` - Usuarios del sistema
- `roles` - Roles y permisos
- `sessions` - Sesiones activas

### Schema: properties

Datos inmobiliarios:
- `properties` - Catalogo de propiedades
- `property_types` - Tipos (casa, depto, etc)
- `locations` - Ubicaciones geograficas
- `valuations` - Historial de valuaciones

### Schema: analytics

Datos analiticos:
- `market_trends` - Tendencias de mercado
- `price_indices` - Indices de precios
- `reports` - Reportes generados

---

## Flujos Principales

### Autenticacion

```
1. Usuario envia credenciales
2. Backend valida con LocalStrategy
3. Si valido, genera JWT
4. Frontend almacena token
5. Requests subsecuentes incluyen Bearer token
6. JwtAuthGuard valida en cada request protegido
```

### Consulta de Analytics

```
1. Frontend solicita datos del dashboard
2. Backend verifica cache en Redis
3. Si cache hit, retorna datos
4. Si cache miss:
   a. Consulta PostgreSQL
   b. Procesa/agrega datos
   c. Almacena en cache
   d. Retorna al frontend
5. Frontend renderiza visualizaciones
```

---

## Decisiones Arquitectonicas

| ID | Titulo | Estado |
|----|--------|--------|
| [ADR-001](../97-adr/ADR-001-stack-tecnologico.md) | Stack Tecnologico | Aceptado |

---

## Seguridad

### Autenticacion
- JWT con expiracion configurable
- Refresh tokens para renovacion
- Bcrypt para hash de passwords

### Autorizacion
- RBAC (Role-Based Access Control)
- Guards en endpoints protegidos
- Validacion de permisos por recurso

### Comunicacion
- HTTPS obligatorio en produccion
- CORS configurado por ambiente
- Rate limiting en endpoints publicos

---

## Escalabilidad

### Horizontal
- Stateless backend (JWT)
- Sessions en Redis
- Load balancing con Traefik

### Vertical
- Indices optimizados en PostgreSQL
- Query optimization
- Connection pooling

---

## Monitoreo

| Aspecto | Herramienta |
|---------|-------------|
| Logs | stdout + Docker logs |
| Metricas | Prometheus (futuro) |
| Alertas | Alertmanager (futuro) |
| APM | OpenTelemetry (futuro) |

---

## Referencias

- [STACK-TECNOLOGICO.md](./STACK-TECNOLOGICO.md)
- [ADR-001-stack-tecnologico.md](../97-adr/ADR-001-stack-tecnologico.md)
- [service.descriptor.yml](../../apps/backend/service.descriptor.yml)

---

**Documento:** Arquitectura General
**Version:** 1.0.0
**Estado:** Draft
**Ultima actualizacion:** 2026-01-04