Saltar a contenido

Índice — Camunda Platform Architecture Analysis

Punto de entrada del wiki. Empezar cualquier query aquí y seguir los wikilinks.

Sources

(Documentos crudos procesados. Ver raw/.)

Conceptos

(Patrones, protocolos, modelos internos.)

Motor de procesamiento: - concepts/stream-processing — StreamProcessor single-threaded por partición, ProcessingStateMachine, ReplayStateMachine, batch processing. - concepts/command-sourcing — Commands al log antes de procesar, events deterministas, Intent/RecordType system, process banning. - concepts/partitioning — Particiones como persistent streams, key encoding (13-bit partition + 51-bit key), routing strategies. - concepts/raft-consensus — Roles, leader election, log replication via quorum commit, joint consensus para reconfiguración. - concepts/rocksdb-state-store — ZeebeDb wrapper, 142+ column families, snapshots, LogCompactor, TransactionContext. - concepts/backpressure — StabilizingAIMD, dropping vs buffering, whitelisted commands, FlowControl. - concepts/engine-processor-registry — Registro central: ~80 processors, ~25 ValueTypes, BpmnProcessors, listeners, shared behaviors. - concepts/deployment-pipeline — Deploy multi-fase: transform BPMN/DMN, distribute cross-partition, start event subscriptions. - concepts/process-instance-creation — Resolución de proceso, Either-based validation, start instructions, business ID.

BPMN y ejecución: - concepts/bpmn-execution-model — Lifecycle state machine, token model implícito, fork/join, variable scoping, BpmnStreamProcessor. - concepts/bpmn-element-processors — 24 processors (EnumMap), 12 Behavior classes, composition over inheritance. - concepts/dmn-integration — DmnScalaDecisionEngine, FEEL expressions, binding types, DecisionEvaluation events. - concepts/variable-scoping — Per-element-instance scoping, shadowing, propagación bottom-to-top, mergeLocalDocument vs mergeDocument, schema SQL.

Comunicación y APIs: - concepts/grpc-api — Gateway service RPCs, ActivatedJob structure, streaming, REST API /v2/ mapping. - concepts/job-worker-pattern — External task pattern, activate/stream jobs, timeout, retries, backoff, JobKind. - concepts/message-correlation — Correlation key routing, dedup por messageId, TTL, cross-partition via DEPLOYMENT_PARTITION. - concepts/exporter-system — SPI, at-least-once delivery, position tracking, 4 implementaciones, data pipeline.

Resiliencia: - concepts/timer-system — DueDateTimerCheckScheduler demand-driven, 100ms resolución, YieldingDecorator. - concepts/retry-backoff — JobFailProcessor tres escenarios, backoff duration, JobBackoffCheckScheduler. - concepts/incident-management — Triggers, IncidentResolveProcessor, self-healing, reconstrucción de commands.

Seguridad y multi-tenancy: - concepts/authentication-flow — OIDC multi-IdP, basic auth, gRPC interceptors, JWT validation. - concepts/authorization-model — 20 resource types, 40 permissions, scopes (ID/PROPERTY/ANY), RBAC. - concepts/multi-tenancy — Tenant isolation, transitive resolution, TenantCheck, authorized tenants.

Infraestructura: - concepts/search-infrastructure — 9 módulos, 40+ readers, abstracción multi-backend (ES/OS/RDBMS), índices. - concepts/monorepo-modulos — Jerarquía Maven, 50+ módulos, dependencias críticas, grafo de dependencias internas. - concepts/microbenchmark-methodology — JMH setup oficial: AverageTime mode, 2×5s warmup, 10×10s measurement, 2 forks, GC profiler. - concepts/postgres-monitoring — Queries SQL oficiales: pg_stat_statements, cache hit ratio (>90%), dead tuples (<5%), WAL analysis. - concepts/replay-determinism — Garantía contractual: processing state = replay state, excepciones documentadas (DEFAULT, MIGRATIONS_STATE). - concepts/property-based-testing — Random BPMN models + paths, invariantes universales, reproducibilidad via seeds. - concepts/test-infrastructure — EngineRule, RecordingExporter, fluent builders BPMN, time control inyectable. - concepts/connector-sdk-architecture — OutboundConnectorFunction vs InboundConnectorExecutable, contexts, bindVariables magic, secret resolution, element templates. - concepts/swim-membership-protocol — SWIM: probe 1s + indirect probing + gossip 250ms fanout 2, failure detection 5-10s, threading single-thread. - concepts/failure-detector-formal-properties — Strong Completeness, Speed, Accuracy, Network Load (Chandra-Toueg 1996) + FLP impossibility. Por qué no se puede tener accuracy perfecta + completeness en redes asíncronas. - concepts/infection-style-dissemination — Bailey 1975 epidemic model aplicado a membership; coverage N - N^(-(2λ-2)) después de λ·log(N) rounds; comparison con multicast y LISTEN/NOTIFY. - concepts/incarnation-numbers — Versionado monotónico controlado por el sujeto (analogía AODV destination sequence numbers); preference rules para Suspect/Alive/Confirm; ejemplo end-to-end de resolución de flapping. - concepts/process-instance-migration — Migration: 4 behaviors, 18 element types, 10 precondiciones, BFS iterativo, MIGRATED event. - concepts/development-conventions — Severity heuristic ("data loss = CRITICAL"), build commands, Conventional Commits, review emoji code. - concepts/cluster-internal-protocols — Deployment distribution (ACK + redistribution) + snapshot transfer (chunk-based con CRC32C, reservation pattern). - concepts/sbe-serialization — SBE: 6 design principles (copy-free, native types, allocation-free, streaming, word-aligned, backward compat), 10-50ns encode, decision NO usar en MVP. - concepts/journal-and-stream-platform — 4-layer architecture (engine → stream-platform → logstreams → journal), RecordProcessor interface, doble sequencing, ProcessingResultBuilder. - concepts/atomix-fork-lessons — Lessons del fork: costos reales (build, snapshots, releases), pattern listeners, recomendaciones MVP (skip consensus o usar library existente).

Entidades

(Componentes, módulos, servicios del sistema.)

  • entities/zeebe-broker — Motor distribuido: particiones, Raft, RocksDB, stream processing, exporters.
  • entities/zeebe-gateway — Entry point stateless: gRPC + REST, routing, backpressure, auth interceptors.
  • entities/operate — Monitoring UI: process instances, incidents, flow nodes, batch operations.
  • entities/tasklist — Gestión de user tasks: assignment, forms, search, REST API /v2/.
  • entities/optimize — Analytics y BI: position-based import, branch analysis, bottleneck detection.
  • entities/identity — Auth/AuthZ: OIDC, roles, permisos, multi-tenancy, React SPA.
  • entities/connectors — Runtime de conectores: ~40 pre-built, SDK outbound/inbound, job worker pattern.

Herramientas

(Software, CLIs, servicios mencionados.)

  • (vacío)

Técnicas

(Métodos, patrones, prácticas.)

  • (vacío)

Comparaciones

(Páginas que contrastan dos o más cosas.)

  • comparisons/camunda-8-vs-temporal — Camunda 8 vs Temporal: BPMN vs code-first, RocksDB+exporters vs DB+direct, decisiones para MVP que toma lo mejor de ambos.
  • comparisons/camunda-8-vs-conductor — Camunda 8 vs Netflix Conductor: BPMN XML vs JSON, RocksDB+Raft vs DB externa, built-in tasks (HTTP, DECISION, DO_WHILE).
  • comparisons/camunda-8-vs-argo — Camunda 8 vs Argo Workflows: business vs containerized pipelines, complementarios (no competidores). Sweet spots distintos.

Análisis

(Síntesis cruzada que no pertenece a una sola entidad o concepto.)

  • analysis/c4-architecture-diagrams — 4 niveles C4 en Structurizr DSL: System Context, Container, Component, Code. Pipeline de datos ASCII.
  • analysis/trade-offs-arquitectonicos — 10 decisiones arquitectónicas: command sourcing, single-thread, RocksDB, Raft, gRPC, exporters, keys, composition, backpressure, ES.
  • analysis/mvp-feature-matrix — 3 tiers: 17 esenciales, 18 simplificables, 17 eliminables. Stack sugerido. Estimación LOC ~90% reducción.
  • analysis/blueprint-plataforma-simplificada — Spec de implementación: 9 módulos, schemas SQL, APIs compatibles, plan de 5 fases (8-10 semanas), 10 problemas no-obvios.
  • analysis/scaling-strategy-postgres — Roadmap de 6 fases del MVP a producción: single-node → HA replicas → active-active engines → tenant sharding → Citus → geo-distribución. Triggers cuantitativos por fase.
  • analysis/webapps-architecture-mvp — Estrategia por componente: Operate (build), Tasklist (build), Optimize (skip), Identity (minimal), Modeler (reuse), Connectors (SDK simple). 98% LOC reduction.
  • analysis/operate-tasklist-mvp-detailed — Spec detallado de los 2 webapps prioritarios: 3 sprints cada uno, ~18K LOC total, schemas SQL completos, queries optimizadas, BPMN viewer, JSON Schema forms, real-time updates.
  • analysis/operate-vs-apm-tools — ¿Necesitamos Operate? Hybrid approach: APM (Dynatrace/Datadog) + minimal Process Inspector (2K LOC) + CLI. 7.5K LOC menos que Operate full, mejor monitoring, lower maintenance.

ADRs (Architecture Decision Records)

(25 decisiones arquitectónicas en formato MADR. Ver adrs/index.)

  • adrs/index — Índice completo de 25 ADRs por categoría (core engine, webapps, identity, integration, data, infra)

Self-review iteration

(Meta-análisis crítico y deep-dives en gaps identificados.)

Production readiness iteration

(Security, failure modes, fairness, implementation roadmap concreto.)

Five-iteration deep-dive

(Cinco análisis adicionales para enriquecer el wiki — migration, API, observability, costos, DX.)

  • analysis/migration-from-camunda-8 — Guía exhaustiva: BPMN element mapping (40+ types), FEEL→CEL conversion, state migration strategies, tooling, rollback. Effort 2-3 months para org medium-large.
  • analysis/rest-api-design — REST API spec completo: 60+ endpoints, RFC 7807 errors, cursor pagination, idempotency keys, webhook signing HMAC, OpenAPI 3.0, versioning, CORS, rate limit headers.
  • analysis/observability-deep-dive — Metrics catalog (50+), logs strategy (sampling, redaction), distributed tracing span design, alerts (golden signals + business + failure modes), SLI/SLO + error budgets, dashboard design.
  • analysis/cost-modeling-tco — TCO 3-5 year MVP vs Camunda 8 SaaS/Self-Managed vs Temporal Cloud/Self-Managed. Break-even ~10M instances/year. ROI calculator. Pricing models si SaaS.
  • analysis/developer-experience — DX target: < 30 min al first workflow. Docker Compose quickstart, SDK ergonomics, 20+ examples library, testing patterns (unit/integration/e2e/property), CLI completo, IDE integration.

  • analysis/language-choice — Análisis de pros/cons de 6 lenguajes. Recomendación: Go (score 92/100). Rust segundo (87) si team tiene expertise. Java solo si team viene de Camunda. Genera ADR-026.

  • analysis/sizing-benchmarks — Datos cuantitativos: single-digit ms/nodo, ~50ms service task, sizing 20x, 1GB/partición, RDBMS ~70% de ES.

  • analysis/error-handling-patterns — Flujo end-to-end: retries (FailJob), BPMN errors (ThrowError), incidents, sagas, idempotencia.
  • analysis/service-integration-patterns — Patrones BPMN: sync/async, service task vs send/receive, worker threading, data handling.
  • analysis/intuit-production-benchmarks — Datos reales: 22.74M procesos en 15h, 395 TPS sostenido, TP99 450ms, 15 brokers × 15 partitions.
  • analysis/zeebe-design-philosophy — Por qué Zeebe: stream processing > DB, timeline 2017-2019, decisiones aceptadas y rechazadas.
  • analysis/swim-paper-vs-camunda-defaults — Paper SWIM 2002 vs SwimMembershipProtocolConfig: 4 brechas detectadas (timeout viola constraint paper, round-robin no expuesto, piggyback count opaco, suspicion timeout fijo); recomendaciones para implementación MVP.

Twenty-iteration deep-dive (SDK, ops, compliance, semántica)

(Análisis adicionales: SDK design, CLI, BPMN semantics, testing, DR, multi-region, compliance, adoption.)

Developer experience: - analysis/worker-sdk-go-design — SDK Go: JobHandler API, BPMN errors, OpenTelemetry built-in, testing utilities, comparativa con Zeebe Java SDK. - analysis/cli-tool-design — wf CLI: kubectl-style command surface, shell completion, output formats, scripting-friendly. Comandos por fase M1-M4. - analysis/grpc-vs-rest-tradeoffs — Decisión REST default + gRPC opcional para worker streaming. Performance benchmarks, when each. - analysis/api-versioning-strategy — REST URL path + headers + SDK semver + BPMN namespace + wire protocol. Deprecation 12 meses, sunset 24 meses.

BPMN coverage y semántica: - analysis/bpmn-coverage-matrix — Cobertura BPMN 2.0 por fase: M1 (28 elementos, 80% de procesos), M2 (multi-instance, compensation), M3 (escalation, ad-hoc), M4 (100%). - concepts/compensation-and-bpmn-errors — BPMN errors (boundary), incidents (uncaught), compensation (LIFO + snapshot). Reglas semánticas precisas. - concepts/subprocess-and-call-activity — Embedded subprocess (mismo scope) vs call activity (proceso independiente). Cuándo cuál, variable mapping, performance. - analysis/process-modification-runtime — Cancel element / activate / set vars / resolve incident en instancias en vuelo. API + reglas + audit. Para incident response.

Reliability y testing: - analysis/worker-reliability-patterns — Retry + backoff + circuit breaker + bulkhead + timeout + idempotency + poison messages + graceful degradation. Checklist pre-prod. - analysis/process-testing-framework — Unit, integration (engine in-memory), scenario (testcontainers), load. Stub workers, AdvanceTime, assertions fluentes. - analysis/idempotency-and-deduplication — At-least-once con dedup multi-layer: API ingress (Idempotency-Key), command log, job activation lease, outbox pattern, audit log. - analysis/webhook-delivery-reliability — Webhooks con outbox, retry exponencial, HMAC signature, rate limiting per endpoint, DLQ, SSRF protection.

Operations: - analysis/schema-migration-strategy — Postgres zero-downtime migrations. Expand/migrate/contract pattern. CONCURRENTLY índices. NOT VALID + VALIDATE constraints. Citus considerations. - analysis/disaster-recovery-runbook — RPO/RTO por fase, backup layers (pgBackRest), runbooks por scenario (node/AZ/region failure, corruption, ransomware), chaos drills. - analysis/performance-testing-methodology — 6 workloads referencia (W1-W6), k6 scripts, baseline tracking en CI, capacity calculator, soak tests 24h. - analysis/kubernetes-operator-design — CRDs (WorkflowCluster, Tenant, Process, Worker), reconciliation loops, Patroni integration, GitOps, multi-cluster mesh.

Distribution y strategy: - analysis/multi-region-active-active — 3 modelos: active-passive (DR), active-active per-tenant (sharded), active-active global (Spanner-class). Recomendación: Modelo B opcional M5+. - analysis/open-source-license-strategy — Análisis Apache 2.0 vs BSL vs AGPL vs SSPL. Recomendación: Apache 2.0 + open core. DCO sign-off. Trademark policy. - analysis/adoption-playbook-90-days — Onboarding equipo nuevo: días 0-14 discovery, 15-30 foundations, 31-60 first prod process, 61-90 expansion. Hitos verificables. - analysis/compliance-roadmap — SOC 2 + GDPR + HIPAA: cobertura por phase, controls necesarios, subject request API, BAA, audit trail con hash chain, costos year 1.

Execution plan

(Plan ejecutable para construir el MVP, optimizado para Claude Code spawn agents.)

  • analysis/mvp-implementation-plan-detailed — Plan hyper-detallado: 230 tasks atómicas con TDD obligatorio, criterios de aceptación deterministas, DAG de dependencias por waves, quality gates por fase, toolchain completo de static analysis (golangci-lint, gosec, govulncheck, semgrep, SonarQube, trivy, syft, cosign), CI/CD pipeline, prompt templates para spawn de agents, definition of done.