Systems

These are the cross-cutting internal frameworks that the services compose. Each one has clear architectural boundaries but doesn't map cleanly to a single deployable unit. A change in any of these is felt across the cluster.

System	Lives in	What it provides
CHASM	chasm/	Generalised state-machine framework. Workflow / Scheduler / Nexus build on it.
HSM	service/history/hsm/	Pre-CHASM hierarchical state-machine library used by callbacks and Nexus.
Persistence	common/persistence/	Pluggable storage interface (Cassandra, MySQL, PG, SQLite).
Replication / XDC	service/history/replication/, service/worker/replicator/	Multi-cluster replication of namespaces and history events.
Membership	common/membership/	Ringpop-based gossip ring; shard / partition ownership.
Dynamic config	common/dynamicconfig/	Runtime-tunable settings injected via fx.
Archival	common/archiver/, service/history/archival/	Long-term storage of completed histories.
Telemetry	common/telemetry/, common/log/, common/metrics/	Logs, metrics, OpenTelemetry traces.

Where systems intersect with services

graph TD
    FE[Frontend] --> Auth[Authorization]
    FE --> NS[Namespace cache]
    FE --> Quotas[Rate limiters]

    H[History] --> CHASM[CHASM]
    H --> HSM[HSM]
    H --> Persist[Persistence]
    H --> Replication[Replication]
    H --> Archival[Archival]

    M[Matching] --> Persist
    M --> Membership[Membership]

    W[Internal Worker] --> Replication
    W --> Persist

    All[All services] --> DynCfg[Dynamic config]
    All --> Telemetry[Telemetry]
    All --> Membership

The most cross-cutting are membership, dynamic config, and telemetry — every service depends on them.

Reading order

If you are new to the codebase, the most useful order is:

1. Persistence — to understand the data model.
2. Membership — to understand how shards move between hosts.
3. CHASM and HSM — to understand how the engine is moving from custom state machines to a generic framework.
4. Replication — to understand how multi-cluster works.
5. Archival and Telemetry — operationally important but smaller surfaces.