C4 Architecture Diagrams

Diagramas C4 (Context, Container, Component, Code) de la arquitectura de Camunda 8, en Mermaid C4. Cada nivel revela progresivamente más detalle del sistema, desde la vista de contexto hasta los componentes internos del engine.

Level 1 — System Context

C4Context
    title System Context — Camunda Platform 8

    Person(user, "Process Developer", "Diseña y opera workflows BPMN")
    Person(operator, "Platform Operator", "Monitorea y administra el cluster")
    System_Ext(externalSystem, "External Service", "Microservicios que ejecutan tareas")

    System(camunda, "Camunda Platform 8", "Plataforma de orquestación de procesos BPMN")

    Rel(user, camunda, "Deploys processes, starts instances, monitors", "gRPC / REST / HTTPS")
    Rel(operator, camunda, "Manages users, analyzes bottlenecks", "HTTPS")
    Rel(externalSystem, camunda, "Activates & completes jobs", "gRPC / REST")

    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

Level 2 — Container (Detalle interno)

C4Container
    title Container — Camunda Platform 8

    Person(user, "Process Developer", "Diseña y opera workflows")
    Person(operator, "Platform Operator", "Monitorea y administra")
    System_Ext(externalSystem, "External Service", "Microservicios externos")

    System_Boundary(camunda, "Camunda Platform 8") {
        Container(gateway, "Zeebe Gateway", "Java (Netty)", "Stateless. gRPC + REST. Auth interceptors.")
        Container(broker1, "Broker Node 1", "Java", "Partitions 1(L), 2(F), 3(F)")
        Container(broker2, "Broker Node 2", "Java", "Partitions 1(F), 2(L), 3(F)")
        Container(broker3, "Broker Node 3", "Java", "Partitions 1(F), 2(F), 3(L)")
        ContainerDb(es, "Elasticsearch", "ES 8.x", "operate-list-view, tasklist-task, zeebe-record-*")
        ContainerDb(rdbms, "PostgreSQL", "PostgreSQL", "Identity data, RDBMS exporter target")
        Container(operate, "Operate", "Spring Boot + React", "Process monitoring. REST API /v2/.")
        Container(tasklist, "Tasklist", "Spring Boot + React", "User task mgmt. REST /v2/.")
        Container(optimize, "Optimize", "Spring Boot + React", "Process analytics. Position-based import.")
        Container(identity, "Identity", "React SPA", "Auth/AuthZ UI.")
        Container(connectors, "Connector Runtime", "Spring Boot", "~40 connectors. Job worker pattern.")
    }

    Rel(user, gateway, "Deploys, starts", "gRPC / REST")
    Rel(user, operate, "Monitors", "HTTPS")
    Rel(user, tasklist, "Completes tasks", "HTTPS")
    Rel(operator, optimize, "Analyzes", "HTTPS")
    Rel(operator, identity, "Manages users", "HTTPS")

    Rel(gateway, broker1, "Partition-aware routing", "gRPC internal")
    Rel(gateway, broker2, "Commands", "gRPC")
    Rel(gateway, broker3, "Commands", "gRPC")

    BiRel(broker1, broker2, "Raft replication", "Netty")
    BiRel(broker2, broker3, "Raft replication", "Netty")
    BiRel(broker3, broker1, "Raft replication", "Netty")

    Rel(broker1, es, "CamundaExporter + ESExporter", "HTTP bulk")
    Rel(broker2, es, "Exporters", "HTTP bulk")
    Rel(broker3, es, "Exporters", "HTTP bulk")

    Rel(operate, es, "Search queries", "REST")
    Rel(tasklist, es, "Search queries", "REST")
    Rel(optimize, es, "Position-based import", "REST")
    Rel(identity, rdbms, "Reads/writes identity data", "JDBC")

    Rel(connectors, gateway, "Job activation & completion", "gRPC")
    Rel(externalSystem, gateway, "Activates & completes jobs", "gRPC / REST")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Level 3 — Component (Zeebe Broker internals)

C4Component
    title Component — Zeebe Broker internals

    Container_Ext(gateway, "Zeebe Gateway", "Java", "Forwards commands")
    ContainerDb_Ext(es, "Elasticsearch", "ES 8.x", "Search backend")

    Container_Boundary(broker, "Zeebe Broker") {
        Component(streamProcessor, "StreamProcessor", "Java", "Single-threaded Actor per partition. Orchestrates processing.")
        Component(processingStateMachine, "ProcessingStateMachine", "Java", "Read → Process → Write → UpdateState → SideEffects loop")
        Component(replayStateMachine, "ReplayStateMachine", "Java", "Rebuilds state from log after restart. Replays EVENT records.")

        Component(engine, "Engine", "Java", "RecordProcessor impl. Dispatches to TypedRecordProcessors.")
        Component(bpmnStreamProcessor, "BpmnStreamProcessor", "Java", "Central BPMN dispatcher. Routes to element processors.")
        Component(elementProcessors, "Element Processors", "Java", "24 processors (one per BPMN type). Composition via Behaviors.")
        Component(eventAppliers, "EventAppliers", "Java", "State mutation: (Intent, version) → TypedEventApplier.")

        Component(raftPartition, "RaftPartition", "Atomix/Java", "Raft consensus group per partition.")
        Component(raftLog, "RaftLog", "Java", "Segmented journal (file-based). ApplicationEntry batches.")
        Component(logStream, "LogStream", "Java", "Append-only log abstraction with FlowControl.")

        ComponentDb(zeebeDb, "ZeebeDb", "Java/JNI", "RocksDB wrapper. 142+ column families. Type-safe access.")
        ComponentDb(snapshotStore, "SnapshotStore", "Java", "RocksDB checkpoints. Chunk-based transfer. LogCompactor.")

        Component(exporterDirector, "ExporterDirector", "Java", "Reads log, dispatches to configured exporters.")
        Component(esExporter, "ElasticsearchExporter", "Java", "Bulk indexing: 1000 recs / 10MB / 5s flush.")
        Component(camundaExporter, "CamundaExporter", "Java", "60+ ExportHandlers. Produces webapp entities.")

        Component(timerScheduler, "DueDateTimerCheckScheduler", "Java", "Demand-driven timer firing. 100ms resolution.")
        Component(jobBackoffScheduler, "JobBackoffCheckScheduler", "Java", "Backoff timer for failed jobs.")
    }

    Rel(gateway, streamProcessor, "Commands")

    Rel(streamProcessor, processingStateMachine, "Delegates processing")
    Rel(streamProcessor, replayStateMachine, "Delegates replay")
    Rel(processingStateMachine, engine, "processCommand()")
    Rel(replayStateMachine, engine, "replay()")
    Rel(engine, bpmnStreamProcessor, "BPMN commands")
    Rel(bpmnStreamProcessor, elementProcessors, "Lifecycle dispatch")
    Rel(engine, eventAppliers, "Apply state changes")

    Rel(processingStateMachine, logStream, "Read commands / write events")
    Rel(logStream, raftLog, "Append entries")
    Rel(raftPartition, raftLog, "Replicate via quorum")

    Rel(processingStateMachine, zeebeDb, "Transaction: read/write state")
    Rel(zeebeDb, snapshotStore, "Periodic snapshots")

    Rel(exporterDirector, logStream, "Read committed records")
    Rel(exporterDirector, esExporter, "Forward records")
    Rel(exporterDirector, camundaExporter, "Forward records")
    Rel(esExporter, es, "Bulk index", "HTTP")
    Rel(camundaExporter, es, "Bulk index", "HTTP")

    Rel(timerScheduler, processingStateMachine, "Write TRIGGER commands")
    Rel(jobBackoffScheduler, processingStateMachine, "Write RECUR_AFTER_BACKOFF")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Level 4 — Code (Processing Pipeline Detail)

Mermaid no tiene un nivel C4Code dedicado; usamos C4Component para el drill-down al pipeline interno. Las relaciones están en orden de ejecución (top-to-bottom).

C4Component
    title Code — Processing Pipeline (orden de ejecución)

    Container_Boundary(pipeline, "Processing Pipeline (por command)") {
        Component(logStreamReader, "LogStreamReader", "Java", "Lee el próximo COMMAND record del log")
        Component(recordDeserializer, "RecordDeserializer", "Java/SBE", "Deserializa SBE → TypedRecord<T>")
        Component(banChecker, "BanChecker", "Java", "Verifica si el process instance está baneado")
        Component(recordProcessorMap, "RecordProcessorMap", "Java", "(RecordType, ValueType, Intent) → Processor")

        Component(bpmnElementLookup, "Process Cache", "Java", "ExecutableProcess + elemento BPMN por elementId")
        Component(stateTransitionGuard, "StateTransitionGuard", "Java", "Valida transición de estado del elemento")

        Component(processorRegistry, "BpmnElementProcessors", "Java", "EnumMap<BpmnElementType, Processor>. 24 processors.")
        Component(behaviors, "BpmnBehaviors", "Java", "Composition: JobBehavior, IncidentBehavior, VariableMapping, EventSubscription, ...")

        Component(resultBuilder, "ProcessingResultBuilder", "Java", "Accumula follow-up records (events, commands, rejections)")
        Component(transactionContext, "TransactionContext", "Java", "RocksDB transaction. Commit atómico con log write.")
        Component(sideEffects, "SideEffects", "Java", "Client responses, post-commit tasks")
    }

    Rel(logStreamReader, recordDeserializer, "Raw bytes")
    Rel(recordDeserializer, banChecker, "TypedRecord")
    Rel(banChecker, recordProcessorMap, "If not banned")
    Rel(recordProcessorMap, bpmnElementLookup, "For BPMN commands")
    Rel(bpmnElementLookup, stateTransitionGuard, "ExecutableFlowElement")
    Rel(stateTransitionGuard, processorRegistry, "If valid transition")
    Rel(processorRegistry, behaviors, "Delegate shared logic")
    Rel(processorRegistry, resultBuilder, "Write follow-up records")
    Rel(resultBuilder, transactionContext, "Commit state + log")
    Rel(transactionContext, sideEffects, "Post-commit")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Diagrama de datos: Export Pipeline

flowchart TD
    subgraph Broker["Zeebe Broker"]
        Commands[Commands gRPC] --> StreamProc[StreamProcessor single-threaded]
        StreamProc --> Events[Events append to log]
        Events --> ExporterDirector[ExporterDirector reads committed records]
        ExporterDirector --> ESExporter[ES Exporter raw idx]
        ExporterDirector --> CamundaExporter[Camunda Exporter 60+ handlers]
    end

    subgraph ESCluster["Elasticsearch / OS"]
        ZeebeRecord[(zeebe-record-* raw events)]
        OperateIdx[(operate-list-view, tasklist-task, etc.)]
    end

    ESExporter --> ZeebeRecord
    CamundaExporter --> OperateIdx

    ZeebeRecord --> Optimize[Optimize position import]
    OperateIdx --> SearchInfra[Search Infra 40+ readers]
    SearchInfra --> RestAPI[REST API /v2 gateway-rest]
    RestAPI --> OperateUI[Operate UI]
    RestAPI --> TasklistUI[Tasklist UI]

Notas sobre Mermaid C4 vs Structurizr DSL

• Mermaid C4 es soportado en Obsidian, GitHub, GitLab y muchos renderers sin tooling extra. Marcado como "experimental" en docs Mermaid pero estable en producción.
• Structurizr DSL sigue siendo la opción canónica si el equipo trabaja con structurizr.com (autolayout, múltiples views desde un solo modelo, exports a PlantUML/Mermaid/dot).
• Para wiki + version control + zero-tooling, Mermaid es preferible.
• Mermaid C4 NO soporta C4Code (Level 4); usamos C4Component para drill-downs.
• Sintaxis elements clave:
• Person, Person_Ext
• System, SystemDb, SystemQueue, System_Ext, SystemDb_Ext, SystemQueue_Ext
• Container, ContainerDb, ContainerQueue, Container_Ext, ContainerDb_Ext
• Component, ComponentDb, ComponentQueue, Component_Ext
• System_Boundary, Container_Boundary, Enterprise_Boundary
• Rel, BiRel, Rel_Up, Rel_Down, Rel_Left, Rel_Right

Referencias

• Mermaid C4 docs (experimental)
• C4 model — Simon Brown
• Structurizr DSL reference