EventMesh Architecture Guard

Issue: #5305 (P0), #5322 (fail-mode), #5342 (Q7 expansion)

This document is the canonical reference for the eventmesh-architecture-guard module. It explains every ArchUnit rule, its rationale, and how to add a new one.

If you are a contributor opening a PR that touches one of the analysed modules, read this first -- it tells you which boundaries you must respect and what to expect if you cross one.

How it works

The eventmesh-architecture-guard Gradle module runs an ArchUnit analysis across the production classpath on every build (and in CI). Every rule is asserted in FAIL mode (rule.check(classes) throws on violation), so a boundary break fails the build.

The CI workflow at .github/workflows/architecture-guard.yml runs the analysis as its own check on every PR that touches the analysed modules, so a violation appears as "Architecture Guard" on the PR rather than buried in the 30-minute Build job log.

The list of analysed modules (i.e. what triggers the workflow and what shows up in the classpath for loadProductionClasses()):

Module	Reason for analysis
eventmesh-common	source of common.internal.., common.protocol.*
eventmesh-runtime	source of runtime.tcp.internal.., etc.
eventmesh-spi	guaranteed "outside" package for that-clauses
eventmesh-protocol-plugin	meshmessage / SDKs / protocol sub-packages
eventmesh-storage-plugin (kafka only)	the storage plugin canary for ruleStoragePlugins*
eventmesh-connector-api	connector SPI boundary
eventmesh-connector-runtime	runtime classes named in ruleConnector*
eventmesh-connector-plugin:eventmesh-connector-file	the connector plugin canary for ruleConnector*

Severity: FAIL

Earlier versions used a *_warn rule shape that logged violations to SLF4J but never failed. That mode was silent because the test module has no SLF4J binding on its runtime classpath -- LoggerFactory hands back the NOP logger and every LOG.warn(report) was discarded. All rules now use rule.check(classes) in the JUnit test, which throws AssertionError with a per-class violation report.

Rules (12 total)

eventmesh-common boundaries (5)

#	Rule	Forbids
1	ruleInternalHidden	org.apache.eventmesh.common.internal.. reached from outside org.apache.eventmesh.common..
2	ruleHttpProtocolHidden	org.apache.eventmesh.common.protocol.http.. from modules other than meshmessage / sdks
3	ruleGrpcProtocolHidden	org.apache.eventmesh.common.protocol.grpc.. from modules other than meshmessage / sdks
4	ruleTcpProtocolHidden	org.apache.eventmesh.common.protocol.tcp.. from modules other than meshmessage / sdks / runtime
5	ruleOldUtilsRenamed	org.apache.eventmesh.common.utils.. (renamed to .util.. in #5298)

eventmesh-runtime boundaries (4)

#	Rule	Forbids
6	ruleRuntimeTcpInternalHidden	runtime.tcp.internal.. reached from outside runtime.tcp..
7	ruleRuntimeEngineIsolatedFromInfra	runtime.boot / ingress / delivery depending on runtime.tcp.internal..
8	ruleRuntimePushDoesNotImportCodec	runtime.push depending on runtime.tcp.internal..
9	ruleRuntimeSubscriptionStateIsolated	runtime.ingress depending on runtime.state.internal..

Plugin SPI boundaries (3)

#	Rule	Forbids
10	ruleConnectorPluginsDependOnlyOnSpi	org.apache.eventmesh.connector.<plugin>.. depending on connector-runtime internals by name
11	ruleStoragePluginsIsolated	one storage plugin's package reaching into another storage plugin's package
12	ruleStoragePluginsDependOnlyOnApi	a storage plugin depending on eventmesh.runtime.. or eventmesh.connector.runtime..

How to add a new rule

1. Open ArchitectureRules.java in eventmesh-architecture-guard/src/main/java/org/apache/eventmesh/architecture/guard/.
2. Add a public static ArchRule ruleXxx = noClasses()... (or classes()...) field. End the chain with .because("...") so the violation report tells the reader what to fix.
3. Add a void ruleXxx_check() { ArchitectureRules.ruleXxx.check(classes); } method in ArchitectureRulesTest. The test method MUST be named *_check (the B mode that fails on violation).
4. If your rule targets a module not yet in the testImplementation list of eventmesh-architecture-guard/build.gradle, add it.
5. Update the rule table in this document.
6. Run ./gradlew :eventmesh-architecture-guard:architectureCheck to confirm your rule loads and the test passes on a clean tree.

Running locally

./gradlew :eventmesh-architecture-guard:architectureCheck
# or, for the JUnit form (FAIL mode):
./gradlew :eventmesh-architecture-guard:test

CI

.github/workflows/architecture-guard.yml runs the same task as its own check on pushes and pull requests that touch the analysed modules. The matrix build in ci.yml excludes :eventmesh-architecture-guard:test to avoid running the rules twice.

Intentional-violation proof (issue #5342 acceptance)

Issue #5342 asks for "an intentional-violation PR that proves the guard catches violations." We achieve this without a separate PR by shipping two canary classes in src/test/java/:

• org.apache.eventmesh.connector.fakeplugin.FakePluginCanary (introduced in PR #5328) -- reaches into org.apache.eventmesh.connector.ConnectorRuntime. The companion ArchitectureRulesTest.ruleConnectorPluginsDependOnlyOnSpiCatchesViolations asserts the rule fails with the canary class named in the report.
• org.apache.eventmesh.storage.fakeplugin.FakeStorageCanary (introduced in this issue) -- reaches into org.apache.eventmesh.storage.rocketmq5.storage. The companion ruleStoragePluginsIsolated_catches test asserts the same shape for the storage plugin boundary.

These canaries live in src/test/java/ so production code stays clean, and the production rule (DO_NOT_INCLUDE_TESTS) is exercised by a focused unit test that re-imports the canary package. This is the same pattern ArchUnit's own examples use for "prove the rule works."

Further reading

• docs/feature/storage-spi.md -- the storage capability matrix
• eventmesh-architecture-guard/README.md -- module-level summary
• CONTRIBUTING.md -- how to add a new module