inmobiliaria-analytics/docs/00-vision-general/ARQUITECTURA-GENERAL.md

id	title	type	version	status	created_date	updated_date
ARCH-IA	Arquitectura General - Inmobiliaria Analytics	Architecture Document	1.0.0	Draft	2026-01-04	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	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
• ADR-001-stack-tecnologico.md
• service.descriptor.yml

---

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