Arquitectura General del Backend Bimtrazer
Documento Generado mediante análisis estático del código fuente.
Fecha: 2026-05-01
Campos marcados con[inferido]indican interpretación basada en estructura y nombres.
1. Vista General del Sistema
Bimtrazer es una plataforma de gestión de proyectos de construcción basada en BIM (Building Information Modeling). El backend está compuesto por 18 microservicios independientes que se comunican principalmente mediante HTTP REST. No se detectó uso de colas de mensajería asincrónica (RabbitMQ, Kafka, NATS) ni WebSockets en ningún servicio.
2. Catálogo de Servicios
| # | Servicio | Lenguaje | Puerto | Rol Principal |
|---|---|---|---|---|
| 1 | blocks |
Go / Gin | 8104 | Gestión de bloques (elementos de trabajo BIM) |
| 2 | budget |
Go / Gin | 8118 | Control presupuestario (gasto, compromiso, presupuesto) |
| 3 | digitaltwin |
Go / Gin | 8107 | Visualización 3D del modelo (gemelo digital) |
| 4 | displacements |
Go / Gorilla Mux | 8105 | Motor de cálculo de desplazamientos de cronograma |
| 5 | ifc |
Go / Gin | 8101 | Gestión de archivos IFC y versiones de modelo |
| 6 | items |
Go / Gin | 8115 | Componentes presupuestarios y recursos |
| 7 | labels |
Go / Gin | 8102 | Gestión de etiquetas (CORE del sistema) |
| 8 | lblsref |
Go / Gin | 8099/8106 | Cálculo de referencias y pesos entre etiquetas |
| 9 | lbp |
TypeScript / Express | 8080 | Procesamiento y mapeo de bloques Lean BIM |
| 10 | media |
Go / Gin | 8114 | Almacenamiento de fotografías y videos de obra |
| 11 | messages |
Go / Gin | 8113 | Auditoría y notificaciones de eventos |
| 12 | projects |
Go / Gin | 8099 | Gestión del ciclo de vida de proyectos |
| 13 | registry |
Go / Gin | 8110 | Certificación de bloques de construcción |
| 14 | sequences |
Go / Gin | 8103 | Análisis de dependencias y rutas críticas |
| 15 | users |
Go / Gin | variable | Autenticación y gestión de usuarios |
| 16 | worktables |
Go / Gin | variable | Reportes, dashboards y generación de PDF |
| 17 | s3-manager-ms |
Node.js / Express | 3002 | Gestión de archivos IFC en AWS S3 |
| 18 | json-block-list |
Node.js / Express | 3060 | Consulta y comparación de catálogos de bloques |
3. Mapa de Comunicaciones entre Servicios
flowchart TD
FE["🖥 Frontend / Portal React\napibt.bimtrazer.com"]
FE -->|HTTP REST + JWT| GW["🔀 API Gateway\napibt.bimtrazer.com"]
GW --> US["users\n:8105"]
GW --> PR["projects\n:8099"]
GW --> IFC["ifc\n:8101"]
GW --> BL["blocks\n:8104"]
GW --> LB["labels\n:8102"]
GW --> REG["registry\n:8110"]
GW --> MED["media\n:8114"]
GW --> DT["digitaltwin\n:8107"]
GW --> BUD["budget\n:8118"]
GW --> WK["worktables"]
GW --> S3["s3-manager-ms\n:3002"]
GW --> JBL["json-block-list\n:3060"]
IFC -->|POST /sequences| SEQ["sequences\n:8103"]
IFC -->|POST /blocks/create-codes| PR
LB -->|PUT /labels-calculation| LBLR["lblsref\n:8106"]
REG -->|POST /map-and-update| LBP["lbp\n:8080"]
REG -->|PUT /workprogress| DISP["displacements\n:8105"]
REG -->|POST /| MSG["messages\n:8113"]
MED -->|POST /| MSG
MED -->|POST /map-and-update| LBP
DT -.-|env ref| DISP
DT -.-|env ref| LB
LBP -->|POST /| MSG
4. Estilos de Comunicación
| Estilo | Uso en Bimtrazer |
|---|---|
| HTTP REST síncrono | Comunicación principal entre TODOS los servicios |
| HTTP async (goroutine) | Media llama a LBP en goroutine sin esperar respuesta |
| No hay colas de mensajes | No se detectó RabbitMQ, Kafka, NATS ni similar |
| No hay WebSockets | No hay comunicación en tiempo real push |
| No hay gRPC | Todo es HTTP/JSON |
| Llamadas en cascada | Registry → LBP → Messages (encadenamiento síncrono) |
5. Patrones Arquitectónicos Identificados
5.1 Microservicios con Base de Datos por Proyecto
Cada proyecto tiene su propia base de datos MongoDB con el mismo esquema. Un servidor MongoDB centralizado (54.92.218.217:27017) actúa como hub, y cada proyecto puede tener también su instancia dedicada ({projectId}.bimtrazer.com:27017).
5.2 Pool de Conexiones Dinámico
Todos los servicios Go implementan un DatabasePool thread-safe que crea conexiones por proyecto bajo demanda y las reutiliza. Evita crear conexiones en cada request.
5.3 Multi-ambiente con Variables de Entorno por Prefijo
Todos los servicios usan el patrón {ENVIRONMENT}_{VARIABLE}: - DEV_PORT, QA_PORT, PROD_PORT - DEV_DB_HOST, QA_DB_HOST, PROD_DB_HOST
La variable ENVIRONMENT selecciona el conjunto activo.
5.4 Handler → Controller → Helper
Los servicios Go siguen una arquitectura en capas: - Handler: recibe y parsea el request HTTP - Controller: consulta a MongoDB - Helper: lógica de negocio pura (cálculos, transformaciones)
5.5 Modelo Central + Modelo por Proyecto
masterDB: registro global de proyectos y usuarios{projectId}DB: datos de cada proyecto (bloques, etiquetas, media, mensajes)
5.6 Certificación en Cascada (Saga sin transacciones)
El proceso de certificación de un bloque desencadena múltiples actualizaciones en otros servicios sin mecanismo de compensación formal. Si algún paso falla, puede haber inconsistencia.
6. Tecnologías Clave
Lenguajes y Frameworks
| Componente | Tecnología |
|---|---|
| Servicios principales | Go 1.23–1.24 |
| Framework HTTP (Go) | Gin-Gonic v1.10–v1.11 |
| Framework HTTP especial | Gorilla Mux v1.8 (solo displacements) |
| Servicios secundarios | TypeScript/Node.js 18+ |
| Framework HTTP (Node) | Express v4.x |
Bases de Datos
| Componente | Tecnología |
|---|---|
| Base de datos principal | MongoDB (sin versión especificada en configs) |
| Driver Go | go.mongodb.org/mongo-driver v1.17.x |
| Driver Node.js (LBP) | Mongoose v8.x |
| Driver Node.js (JSON-block-list) | MongoDB driver nativo v6.x |
| Almacenamiento de archivos | Sistema de archivos local montado en /mnt/s3storage/ |
| Almacenamiento nube | AWS S3 (vía s3-manager-ms) |
Librerías Especiales
| Librería | Uso |
|---|---|
xuri/excelize |
Generación y lectura de archivos Excel (.xlsx) |
gomail.v2 |
Envío de emails vía SMTP |
go-wkhtmltopdf |
Generación de PDF desde HTML |
disintegration/imaging |
Generación de thumbnails de imágenes |
@aws-sdk/client-s3 |
Upload de archivos IFC a AWS S3 |
CI/CD
- Todos los servicios Go tienen
.gitlab-ci.yml→ se usa GitLab CI/CD - Dockerized: todos tienen
Dockerfilecon build multi-stage- Builder:
golang:1.24-bullseye - Runtime:
ubuntu:22.04
- Builder:
7. Modelo de Datos Global
Base de datos master (centralizada)
| Colección | Propósito |
|---|---|
projects |
Registro maestro de todos los proyectos |
users |
Registro global de usuarios |
manager_person |
Permisos de certificación por usuario/proyecto |
free_days |
Días festivos/no laborales |
Base de datos {projectId} (por proyecto)
| Colección | Propósito | Servicio principal |
|---|---|---|
blockIfc |
Bloques/elementos del modelo BIM | blocks, ifc, displacements |
blockIfc_sequences |
Secuencias de dependencias calculadas | sequences |
labels |
Etiquetas y jerarquía de trabajo | labels, lblsref |
labelGroups |
Agrupaciones de etiquetas | labels |
plan_records |
Registros históricos de planificación | labels |
plan_freezing_past |
Planificación congelada del pasado | labels |
compressions |
Factores de compresión de proyecciones | labels |
label_report |
Reportes precalculados de avance | worktables |
blockImgs |
Metadatos de imágenes de bloques | media |
blockMsgs |
Mensajes y eventos de bloques | messages |
worktables |
Definición de mesas de trabajo/dashboards | worktables |
ifc |
Metadatos de archivos IFC cargados | ifc |
project_config |
Configuración específica del proyecto | projects |
items |
Componentes presupuestarios | items |
budget_records |
Registros de presupuesto | budget |
committed_records |
Registros de compromisos | budget |
spent_records |
Registros de gasto | budget |
leanbim_blocks |
Bloques procesados en formato Lean BIM | lbp |
labels_ref |
Referencias y pesos entre etiquetas | lblsref |
certification_queue |
Cola de certificaciones pendientes | registry |
execution_history |
Auditoría de ejecuciones | registry |
8. Flujos Macro de Negocio
Flujo A: Incorporación de Modelo BIM
1. Usuario sube archivo IFC → s3-manager-ms (AWS S3)
2. ifc evalúa hash, detecta versión nueva
3. ifc crea bloques → sequences (calcula dependencias)
4. ifc genera códigos → projects
5. labels asigna bloques a etiquetas con pesos
6. labels calcula planificación y gráficos
7. lblsref propaga pesos en cascadaFlujo B: Certificación de Avance de Obra
1. Usuario certifica bloque con % avance → registry
2. registry valida usuario, permisos y dependencias preladas
3. registry actualiza blockIfc en MongoDB
4. registry notifica → lbp (sincroniza Lean BIM)
5. registry notifica → messages (registra evento de auditoría)
6. registry notifica → worktables (recalcula reportes)
7. labels recalcula pesos y avance de etiqueta padre
8. displacements recalcula fechas desplazadas de bloques dependientesFlujo C: Visualización del Gemelo Digital
1. Usuario solicita vista 3D → digitaltwin
2. digitaltwin consulta labels activas y bloques
3. Aplica filtros AND/OR por etiqueta
4. Devuelve datos de geometría (dbIds, GUIDs, estados)
5. Frontend renderiza modelo coloreado por estadoFlujo D: Reporte de Progreso
1. Usuario solicita reporte → worktables
2. worktables lee label_report (precalculado)
3. Genera PDF con wkhtmltopdf (HTML → PDF)
4. Incluye imágenes de bloques desde /mnt/s3storage/
5. Comprime PDF (gzip) y codifica en base64
6. Envía al frontend9. Consideraciones de Seguridad (resumen)
IMPORTANTE: Se detectaron configuraciones sensibles en el código fuente que deben migrarse urgentemente a sistemas de gestión de secretos (HashiCorp Vault, AWS Secrets Manager, variables de entorno protegidas en CI/CD).
- Credenciales de base de datos presentes en archivos de configuración de código fuente
- Token JWT de acceso interno con expiración muy larga presente en código
- Credencial SMTP de email visible en código fuente del servicio
labels - CORS abierto (
*) en la mayoría de los servicios - Sin rate limiting en endpoints públicos
- Sin API Gateway centralizado de autenticación documentado
10. Métricas del Análisis
| Métrica | Valor |
|---|---|
| Total de servicios identificados | 18 |
| Servicios en Go | 15 |
| Servicios en Node.js/TypeScript | 3 |
| Total de endpoints documentados | ~160 |
| Colecciones MongoDB identificadas | 25+ |
| Flujos de negocio documentados | 4 macro + 15 detallados |
| Servicios con comunicación externa | 8 |
| Herramienta CI/CD | GitLab CI/CD |