Release v2.0.0 · solution-architect · 2026-05-03 · Comité directivo
| # | Principio | Descripción |
|---|---|---|
| P-01 | API-First | El producto se expone exclusivamente como API REST v2. Frontend y SDKs son consumidores, no componentes acoplados. |
| P-02 | English-Only Internals | Todo identificador del sistema en inglés: kinds, estados, endpoints, enums, columnas, códigos de error. |
| P-03 | Stateless & Horizontal Scaling | API sin estado de sesión. Toda autorización viaja en JWT. Pods completamente intercambiables. |
| P-04 | Containerized | Todos los componentes en Docker. Docker Compose (dev) / Kubernetes (prod). |
| P-05 | Observable by Default | Logging JSON estructurado, métricas Prometheus, health checks y tracing distribuido desde R1. |
| P-06 | Multi-Tenant Isolation | Aislamiento garantizado por capa de datos (discriminator column + índices), no por lógica condicional. |
| P-07 | Core Genérico + Perfiles | El core no contiene lógica de dominio. Especialización vía perfiles configurables sin modificar código. |
| P-08 | Seguridad desde R1 | OIDC con Keycloak, JWT validado en cada request, RBAC 5 roles, TLS extremo a extremo. |
| P-09 | Auditabilidad Completa | Toda mutación genera registro de auditoría inmutable con actor, timestamp, acción y diff. |
| Capa | Tecnología | Versión | Origen |
|---|---|---|---|
| Runtime | Quarkus | 3.x LTS | v1 (reutilizado) |
| Lenguaje | Java | 21 LTS | v1 (reutilizado) |
| Base de Datos | PostgreSQL | 16 Alpine | v1 (reutilizado) |
| Vector DB | Qdrant | 1.17 | v1 (reutilizado) |
| Auth (OIDC) | Keycloak | 26.1 | v1 (reutilizado) |
| Embeddings | OpenAI text-embedding-3-large | API | v1 (reutilizado) |
| LLM Validation | OpenAI GPT-4o | API | v1 (reutilizado) |
| Frontend | React + TypeScript | 19.x | Nuevo v2 |
| Contenedores | Docker / Podman | latest | v1 (reutilizado) |
| CI/CD | GitHub Actions + GHCR | — | v1 (reutilizado) |
Exclusiones del MVP: Kafka, Redis, Neo4j, Git/GitHub. PostgreSQL es la fuente canónica de verdad; Qdrant es índice derivado regenerable.
| Criterio | Quarkus 3.x ✓ | Spring Boot 3.x | Micronaut 4.x |
|---|---|---|---|
| Startup | Sub-second (native) | ~3-5s (JVM) | Sub-second (native) |
| Memoria | ~30 MB (native) | ~250 MB (JVM) | ~40 MB (native) |
| OIDC integración | Maduro, Keycloak-first | Spring Security OAuth2 | Micronaut Security |
| Legado equipo | Probado en v1 | Nuevo | Nuevo |
| Dev experience | Hot-reload, live coding | DevTools | Hot-reload |
Decisión (ADR-001): Quarkus 3.x. Stack v1 probado en producción. Startup sub-second, baja huella de memoria, integración nativa Keycloak. Migrar a Spring Boot o Micronaut no justifica la pérdida del conocimiento operativo acumulado.
| Criterio | Qdrant ✓ | Milvus | Weaviate | PGVector |
|---|---|---|---|---|
| Rendimiento top-K | Sub-10ms | Sub-10ms | ~20ms | ~50-100ms |
| Payload filters | Nativos, eficientes | Scalar filters | GraphQL | WHERE SQL |
| Operacionalidad | Binario único | etcd+MinIO+Pulsar | Módulos internos | Extensión PG |
| Legado equipo | Probado en v1 | Nuevo | Nuevo | Nuevo |
Decisión (ADR-003): Qdrant 1.17. Probado en producción. Payload filters nativos críticos para combinar búsqueda semántica con filtros estructurados. Milvus es más complejo operativamente; PGVector compromete rendimiento en filtros combinados.
| Criterio | OpenAI 3-large ✓ | OpenAI 3-small | Cohere Embed v3 | Modelo local (BGE) |
|---|---|---|---|---|
| Calidad MTEB | Top-tier | Muy buena | Excelente | Competitiva |
| Dimensión | 3072 | 1536 | 1024 | 1024 |
| Costo (1M tokens) | ~$0.13 | ~$0.02 | ~$0.10 | $0 (infra propia) |
| Privacidad | API externa | API externa | API externa | Datos locales |
| Operacionalidad | Sin infraestructura | Sin infraestructura | Sin infraestructura | Requiere GPU |
Decisión (ADR-004): OpenAI text-embedding-3-large como base, con abstracción EmbeddingProvider (puerto/adapter) que permite cambiar a cualquier proveedor sin modificar lógica de negocio. Probado en v1 con NDCG@10 0.920.
2 artefactos de despliegue compartiendo un solo código base:
memory-api: API REST v2 — operaciones síncronas (CRUD, búsqueda, revisión)memory-worker: Procesamiento asíncrono — indexación Qdrant, reconciliación| Capa | Contenido |
|---|---|
api/ | REST Resources, DTOs, Exception Mappers |
service/ | 8 servicios de aplicación (Memory, Search, Relation, Entity, Profile, Audit, Tenant, Lifecycle) |
domain/ | 10 entidades + enums (8 kinds, 6 estados, 9 tipos rel., 4 sens.) + value objects |
repository/ | 6 interfaces + 6 implementaciones PostgreSQL |
integration/ | EmbeddingProvider, QdrantClient, LlmProvider, OIDC |
security/ | RBAC, TenantIsolation, SecurityContext |
worker/ | Scheduler + IndexingWorker + ReconciliationWorker |
common/ | ID generation, validación, correlation ID |
| Tabla | Propósito | Detalles clave |
|---|---|---|
memory_fragments | Entidad central | 24 columnas, 8 kinds, 6 estados, 4 niveles de sensibilidad, JSONB para topics/entities/metadata |
relations | Grafo de relaciones | 9 tipos: related_to, depends_on, caused_by, resolves, contradicts, supports, mentions, belongs_to, supersedes |
audit_records | Auditoría inmutable | Diff JSONB con before/after, correlation ID, IP, user agent |
profiles | Perfiles de dominio | Configuración JSONB, versionado |
tenant_configs | Configuración por tenant | Rate limits, max top-K, max graph depth, max batch size |
processing_jobs | Job queue | FOR UPDATE SKIP LOCKED, idempotentes, retry con backoff |
Índices: todos incluyen tenant_id como columna líder. Índices GIN para full-text search sobre content y JSONB sobre topics y extracted_entities. Índice compuesto para filtros combinados frecuentes.
Modelo: PostgreSQL es la fuente canónica de verdad transaccional. Qdrant es un índice derivado regenerable.
processing_jobs en misma transacciónmemory-worker procesa jobs, genera embeddings vía OpenAI, upsert en Qdrant(memory_id, job_type). Retry con backoff exponencial (máx 3 intentos)503 DATABASE_UNAVAILABLEColección Qdrant abax_memories_v2: vector size 3072 · Cosine distance · HNSW index (m=16) · Payload filters: tenant_id, kind, status, topics, entities, importance, confidence, sensitivity.
Regenerable: ante corrupción o cambio de motor de embeddings, se regenera completamente desde PostgreSQL.
tenantId, realm_access.roles| Rol | Alcance |
|---|---|
api-consumer | Buscar y consultar memorias active |
memory-operator | Crear, actualizar, relacionar memorias propias |
memory-reviewer | Aprobar/rechazar memorias en revisión |
memory-admin | Gobernanza total, cross-tenant, config |
memory-auditor | Consultar auditoría, estadísticas, trazabilidad |
tenant_id en todas las tablasTenantIdFilter (interceptor JAX-RS global)404 NOT_FOUNDmemory-admin con registro de auditoría obligatorioEstándares: path prefix /api/v2/ · recursos en plural kebab-case · IDs MEM-xxxxxxxx · paginación offset-based · OpenAPI 3.1 code-first
| Categoría | # | Operaciones |
|---|---|---|
| Memories | 10 | CRUD, search, graph expand, relations, review, extract, batch ingest |
| Entities | 2 | Búsqueda y detalle de entidades extraídas |
| Profiles | 2 | Listar y crear perfiles de dominio |
| Admin/Audit | 3 | Stats de tenant, consulta de auditoría, health checks |
| Health/Metrics | 4 | Health, liveness, readiness, métricas Prometheus |
| OpenAPI | 1 | Especificación OpenAPI 3.1 |
| Total | 22 |
Rate Limiting: 1000 req/min por tenant · 300 req/min por usuario · Burst 5× · Headers X-RateLimit-Remaining, Retry-After
Errores: 13 códigos estructurados con errorCode, message, details[], correlationId para trazabilidad.
| ADR | Decisión | Justificación |
|---|---|---|
| ADR-001 | Quarkus 3.x | Startup sub-second, baja memoria, integración Keycloak nativa, probado en v1. Spring Boot y Micronaut no justifican migración. |
| ADR-002 | Discriminator Column | Simplicidad operativa vs Row-Level Security de PostgreSQL. Filtro global en interceptor JAX-RS. Tests de seguridad automatizados. |
| ADR-003 | Qdrant 1.17 | Payload filters nativos, sub-10ms top-K, binario único. Milvus requiere 4+ servicios; PGVector compromete rendimiento en filtros combinados. |
| ADR-004 | OpenAI + abstracción | Calidad top-tier MTEB (NDCG@10 0.920). Abstracción EmbeddingProvider permite cambiar a modelo local o Cohere sin modificar lógica. |
| ADR-005 | Monolito Modular | Velocidad de desarrollo, simplicidad operativa, transaccionalidad ACID. Preparado para extracción gradual si la escala lo requiere. |
Cada ADR incluye contexto completo, alternativas evaluadas, consecuencias y riesgos en el Documento de Arquitectura (§11).
Pipeline (GitHub Actions): Push a develop/main → Unit tests → Integration tests (Testcontainers) → Build JVM image → Push to GHCR → Deploy staging
Registry: ghcr.io/breisnerlopez/abax-memory-api:v2.0.0
| Ambiente | Estrategia | Orquestador |
|---|---|---|
| Desarrollo local | docker compose up -d | Docker Compose |
| QA | PR preview environment | Docker Compose |
| Staging | Push on main → redeploy inmutable | Kubernetes / Docker Compose |
| Producción | Release tag → deploy manual con aprobación | Kubernetes |
Principios: inmutable (nunca modificar contenedor en ejecución) · rolling update sin downtime · rollback < 5 minutos · health checks liveness/readiness
Capacidad Producción (MVP): 2 réplicas API (2 GB c/u) · 1-2 workers (2 GB) · PostgreSQL 8 GB SSD · Qdrant 4-8 GB · Keycloak 2 réplicas (1 GB c/u)
| # | Riesgo | Prob. | Impacto | Mitigación clave |
|---|---|---|---|---|
| R-01 | Latencia búsqueda > 500ms p95 | Media | Alto | Top-k acotado, payload filters Qdrant, re-ranking opcional |
| R-02 | Fuga de datos cross-tenant | Baja | Crítico | Interceptor global TenantIdFilter, tests CE-07, 404 cross-tenant |
| R-03 | Divergencia PG↔Qdrant | Media | Medio | Workers idempotentes, rebuild desde PostgreSQL |
| R-04 | OpenAI API downtime | Media | Medio | Retry + backoff, abstracción para failover a otro proveedor |
| R-05 | Backlog de jobs creciente | Media | Medio | Monitoreo gauge abax_jobs_pending, auto-scaling worker |
| R-06 | Máquina de estados compleja | Media | Medio | Tests exhaustivos de transiciones, diagrama documentado |
| R-07 | CTEs recursivas lentas (graph) | Media | Medio | max_graph_depth configurable (default 5), caché en R2 |
| R-08 | Extracción futura a microservicios | Baja | Bajo | Bounded contexts con interfaces explícitas, tests ArchUnit |
Complejidad global del MVP: Alta — 66 historias Must, 7 épicas, 22 endpoints, 5 roles RBAC, multi-tenant, búsqueda semántica + grafo + auditoría. Concentrada en SearchService, LifecycleService y Seguridad.
docker-compose.yml con PostgreSQL 16, Qdrant 1.17, Keycloak 26Entregables fundacionales disponibles: