Fase 3 — Diseño Técnico

Abax-Memory v2.0.0 — Arquitectura

Motor genérico de memoria con API REST v2, búsqueda semántica, grafo de conocimiento y gobernanza multi-tenant

Release v2.0.0 · solution-architect · 2026-05-03 · Comité directivo

Agenda

Qué cubre esta presentación

  1. Stack Tecnológico: componentes y alternativas evaluadas
  2. Arquitectura de Servicios: Modulith con 34 paquetes Java
  3. Modelo de Datos: 6 tablas, 14 índices, PostgreSQL canónico
  4. Seguridad: OIDC + RBAC 5×13 + multi-tenant
  5. API Design: 22 endpoints REST v2
  6. ADRs: 5 decisiones arquitectónicas con justificación
  7. CI/CD: Pipeline, GHCR, 4 ambientes
  8. Riesgos Técnicos y Próximos Pasos
Fundamentos

Principios Rectores — 9 pilares

#PrincipioDescripción
P-01API-FirstEl producto se expone exclusivamente como API REST v2. Frontend y SDKs son consumidores, no componentes acoplados.
P-02English-Only InternalsTodo identificador del sistema en inglés: kinds, estados, endpoints, enums, columnas, códigos de error.
P-03Stateless & Horizontal ScalingAPI sin estado de sesión. Toda autorización viaja en JWT. Pods completamente intercambiables.
P-04ContainerizedTodos los componentes en Docker. Docker Compose (dev) / Kubernetes (prod).
P-05Observable by DefaultLogging JSON estructurado, métricas Prometheus, health checks y tracing distribuido desde R1.
P-06Multi-Tenant IsolationAislamiento garantizado por capa de datos (discriminator column + índices), no por lógica condicional.
P-07Core Genérico + PerfilesEl core no contiene lógica de dominio. Especialización vía perfiles configurables sin modificar código.
P-08Seguridad desde R1OIDC con Keycloak, JWT validado en cada request, RBAC 5 roles, TLS extremo a extremo.
P-09Auditabilidad CompletaToda mutación genera registro de auditoría inmutable con actor, timestamp, acción y diff.
Stack Tecnológico

Resumen del Stack MVP

CapaTecnologíaVersiónOrigen
RuntimeQuarkus3.x LTSv1 (reutilizado)
LenguajeJava21 LTSv1 (reutilizado)
Base de DatosPostgreSQL16 Alpinev1 (reutilizado)
Vector DBQdrant1.17v1 (reutilizado)
Auth (OIDC)Keycloak26.1v1 (reutilizado)
EmbeddingsOpenAI text-embedding-3-largeAPIv1 (reutilizado)
LLM ValidationOpenAI GPT-4oAPIv1 (reutilizado)
FrontendReact + TypeScript19.xNuevo v2
ContenedoresDocker / Podmanlatestv1 (reutilizado)
CI/CDGitHub 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.

Stack — Decisión

Runtime: Quarkus 3.x vs Alternativas

CriterioQuarkus 3.x ✓Spring Boot 3.xMicronaut 4.x
StartupSub-second (native)~3-5s (JVM)Sub-second (native)
Memoria~30 MB (native)~250 MB (JVM)~40 MB (native)
OIDC integraciónMaduro, Keycloak-firstSpring Security OAuth2Micronaut Security
Legado equipoProbado en v1NuevoNuevo
Dev experienceHot-reload, live codingDevToolsHot-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.

Stack — Decisión

Vector DB: Qdrant vs Alternativas

CriterioQdrant ✓MilvusWeaviatePGVector
Rendimiento top-KSub-10msSub-10ms~20ms~50-100ms
Payload filtersNativos, eficientesScalar filtersGraphQLWHERE SQL
OperacionalidadBinario únicoetcd+MinIO+PulsarMódulos internosExtensión PG
Legado equipoProbado en v1NuevoNuevoNuevo

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.

Stack — Decisión

Embeddings: OpenAI vs Modelos Locales

CriterioOpenAI 3-large ✓OpenAI 3-smallCohere Embed v3Modelo local (BGE)
Calidad MTEBTop-tierMuy buenaExcelenteCompetitiva
Dimensión3072153610241024
Costo (1M tokens)~$0.13~$0.02~$0.10$0 (infra propia)
PrivacidadAPI externaAPI externaAPI externaDatos locales
OperacionalidadSin infraestructuraSin infraestructuraSin infraestructuraRequiere 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.

Arquitectura

Modular Monolith (Modulith)

2 artefactos de despliegue compartiendo un solo código base:

¿Por qué no microservicios?

34 paquetes Java — Capas estrictas

CapaContenido
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
Modelo de Datos

6 Tablas · 14 Índices · PostgreSQL

TablaPropósitoDetalles clave
memory_fragmentsEntidad central24 columnas, 8 kinds, 6 estados, 4 niveles de sensibilidad, JSONB para topics/entities/metadata
relationsGrafo de relaciones9 tipos: related_to, depends_on, caused_by, resolves, contradicts, supports, mentions, belongs_to, supersedes
audit_recordsAuditoría inmutableDiff JSONB con before/after, correlation ID, IP, user agent
profilesPerfiles de dominioConfiguración JSONB, versionado
tenant_configsConfiguración por tenantRate limits, max top-K, max graph depth, max batch size
processing_jobsJob queueFOR 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.

Integración

Qdrant — Consistencia Eventual Controlada

Modelo: PostgreSQL es la fuente canónica de verdad transaccional. Qdrant es un índice derivado regenerable.

  1. Transacción ACID en PostgreSQL: crear/actualizar memoria + insertar processing_jobs en misma transacción
  2. Indexación asíncrona: memory-worker procesa jobs, genera embeddings vía OpenAI, upsert en Qdrant
  3. Idempotencia: jobs idempotentes por (memory_id, job_type). Retry con backoff exponencial (máx 3 intentos)
  4. Degradación controlada: Qdrant no disponible → API sigue funcionando para CRUD. Búsqueda semántica retorna 503 DATABASE_UNAVAILABLE

Colecció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.

Seguridad

3 Pilares: OIDC · RBAC 5×13 · Multi-Tenant

1. OIDC con Keycloak 26

2. RBAC — 5 Roles × 13 Operaciones

RolAlcance
api-consumerBuscar y consultar memorias active
memory-operatorCrear, actualizar, relacionar memorias propias
memory-reviewerAprobar/rechazar memorias en revisión
memory-adminGobernanza total, cross-tenant, config
memory-auditorConsultar auditoría, estadísticas, trazabilidad

3. Multi-Tenant Isolation — Discriminator Column

API Design

22 Endpoints REST v2

Está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
Memories10CRUD, search, graph expand, relations, review, extract, batch ingest
Entities2Búsqueda y detalle de entidades extraídas
Profiles2Listar y crear perfiles de dominio
Admin/Audit3Stats de tenant, consulta de auditoría, health checks
Health/Metrics4Health, liveness, readiness, métricas Prometheus
OpenAPI1Especificación OpenAPI 3.1
Total22

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.

Decisiones Arquitectónicas

5 ADRs Clave

ADRDecisiónJustificación
ADR-001Quarkus 3.xStartup sub-second, baja memoria, integración Keycloak nativa, probado en v1. Spring Boot y Micronaut no justifican migración.
ADR-002Discriminator ColumnSimplicidad operativa vs Row-Level Security de PostgreSQL. Filtro global en interceptor JAX-RS. Tests de seguridad automatizados.
ADR-003Qdrant 1.17Payload filters nativos, sub-10ms top-K, binario único. Milvus requiere 4+ servicios; PGVector compromete rendimiento en filtros combinados.
ADR-004OpenAI + abstracciónCalidad top-tier MTEB (NDCG@10 0.920). Abstracción EmbeddingProvider permite cambiar a modelo local o Cohere sin modificar lógica.
ADR-005Monolito ModularVelocidad 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

CI/CD y Despliegue

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

AmbienteEstrategiaOrquestador
Desarrollo localdocker compose up -dDocker Compose
QAPR preview environmentDocker Compose
StagingPush on main → redeploy inmutableKubernetes / Docker Compose
ProducciónRelease tag → deploy manual con aprobaciónKubernetes

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)

Riesgos

Riesgos Técnicos — Top 8

#RiesgoProb.ImpactoMitigación clave
R-01Latencia búsqueda > 500ms p95MediaAltoTop-k acotado, payload filters Qdrant, re-ranking opcional
R-02Fuga de datos cross-tenantBajaCríticoInterceptor global TenantIdFilter, tests CE-07, 404 cross-tenant
R-03Divergencia PG↔QdrantMediaMedioWorkers idempotentes, rebuild desde PostgreSQL
R-04OpenAI API downtimeMediaMedioRetry + backoff, abstracción para failover a otro proveedor
R-05Backlog de jobs crecienteMediaMedioMonitoreo gauge abax_jobs_pending, auto-scaling worker
R-06Máquina de estados complejaMediaMedioTests exhaustivos de transiciones, diagrama documentado
R-07CTEs recursivas lentas (graph)MediaMediomax_graph_depth configurable (default 5), caché en R2
R-08Extracción futura a microserviciosBajaBajoBounded 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.

Roadmap

Próximos Pasos

  1. Aprobación de arquitectura por el comité → Gate para Fase 4 (Construcción)
  2. Setup de infraestructura base: docker-compose.yml con PostgreSQL 16, Qdrant 1.17, Keycloak 26
  3. Migraciones Flyway: 6 migraciones incrementales (V1–V7)
  4. Implementación por épica (orden de prioridad):
    • Épica 1: Core de Memorias (CRUD + estados)
    • Épica 2: Búsqueda Semántica (Qdrant + filtros)
    • Épica 3: Relaciones y Grafo
    • Épica 4: Seguridad y Multi-Tenancy
    • Épica 5: Auditoría
    • Épica 6: Perfiles de Dominio
    • Épica 7: Gobernanza y Admin
  5. Revisión de arquitectura post-Épica 2 (validar rendimiento de búsqueda contra CE-04)
Decisión Solicitada

¿Aprobamos esta Arquitectura para la Fase 4 de Construcción?

Entregables fundacionales disponibles:

Sí, aprobamos · Necesitamos ajustes · Revisar en próxima sesión
Referencia

Glosario