Arquitectura
Stack tecnológico
| Capa | Tecnología | Rol |
|---|---|---|
| Frontend | Refine + shadcn/ui + React Flow | UI de gestión y administración |
| Backend | NestJS + TypeScript | API REST, lógica de negocio |
| Base relacional | PostgreSQL + pgvector | Datos estructurados (cuentas, config, permisos, ACL, embeddings RAG) |
| Base documental | MongoDB | Datos dinámicos (expedientes, documentos, tareas, conversaciones AI) |
| Storage | MinIO | Archivos binarios (content-addressed por SHA-256) |
| Auth / IDP | Keycloak | Autenticación multi-tenant, LDAP/AD/SAML |
| Motor de flujos | WorkflowEngineService | Ejecución nativa de workflows + doc-flows Layer 2 |
| LLM Router | LlmRouterService | Cliente unificado Ollama + cloud (OVH/Anthropic/OpenAI/Google/Mistral) con budget tracker por tenant |
| Sidecars | Servicios auxiliares en infra/sidecars/ | Procesadores especializados (OCR, extracción, conversión) |
| Colas | BullMQ + Redis | Jobs asíncronos, reintentos, DLQ |
| Búsqueda | Typesense | Full-text search typo-tolerant |
| Búsqueda semántica | pgvector + Ollama embeddings | RAG sobre documentos indexados |
| Shares | Sidecar WebDAV / SFTP / Samba + S3 gateway | Acceso filesystem-like al repositorio |
| Observabilidad | OpenTelemetry → collector centralizado en repo separado smile-infra-monitor (host 192.168.100.205) + Grafana embebido via auth-proxy + OpenReplay (cloud) | Trazas, métricas, logs, session replay |
Diagrama de arquitectura
Principios de diseño
Separación de responsabilidades por base de datos
PostgreSQL → datos tabulares con JOINs (cuentas, usuarios, config, permisos,
auditoría, ACL fino, embeddings RAG vía pgvector)
MongoDB → datos con schema variable (expedientes, documentos, tareas,
conversaciones del asistente AI)
MinIO → archivos binarios, identificados por SHA-256
Redis → sesiones, parámetros en caché, colas BullMQ
Typesense → índice de búsqueda full-text (replica datos de PG + Mongo)
pgvector → embeddings de chunks documentales para búsqueda semántica (RAG)
Composición Docker
docker-compose.yml— stack completo de desarrollo en una sola red interna: PostgreSQL, MongoDB, Redis, MinIO, Typesense, Keycloak, los sidecars de Shares (sftpgo,samba,rclone-webdav-mount) + OpenLDAP, y los procesadores especializados (libpff-sidecar,kuatia-decompiler,heic-sidecar,raw-sidecar,calibre-sidecar,pandoc-server).docker-compose.ollama.yml— instancia compartida de Ollama corriendo en una VM dedicada; el resto de los stacks (dev, staging, prod) apuntan a ella víaAI_BASE_URL/EMBEDDING_BASE_URL.docker-compose.prod.yml— overrides para producción (variables, imágenes pinneadas).
La observabilidad se exporta al collector centralizado del repo separado Texware-SRL/smile-infra-monitor (host monitor, IP interna 192.168.100.205) vía el endpoint OTLP configurado en OTEL_ENDPOINT=http://192.168.100.205:4317. No hay compose ni scripts locales para SigNoz/Grafana en este repo — el stack centralizado sirve a múltiples proyectos del ecosistema Smile. Si OTEL_ENDPOINT no está seteado, el SDK no arranca y la API funciona normalmente sin telemetría exportada.
Multitenancy
Cada tenant tiene su propio realm en Keycloak. El tenantId viaja en el JWT
y se aplica en absolutamente todos los queries a PostgreSQL y MongoDB.
No hay excepciones.
Content-addressed storage
Los documentos se identifican por el SHA-256 de su contenido. Si el mismo archivo se sube dos veces, Kuatia lo detecta y no duplica el almacenamiento — solo crea una nueva referencia.