server-arch-gates
Skill829 starsChanged 3 years agoMITView on GitHub
Apply Artemis architecture rules when changing server Java or diagnosing an ArchUnit failure.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ci-triageSkill
- client-conventionsSkill
- e2e-pr-checkSkill
- liquibase-migrationSkill
- local-setupSkill
- write-testsSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 61
Every path that stores a new exercise (creation, every kind of import, copies) calls ExerciseConfigurationService.initialize right after …
- Distinctive: line 65
Use modifying queries for feature switches and settings endpoints, preserving configuration ids.
- Very specific: line 80
No direct persistence access: No injected EntityManager or EntityManagerFactory, and no JdbcClient, JdbcTemplate, or DataSource.
- Very specific: line 91
Never touch Hazelcast or Redis directly: All cross-node state goes through DistributedDataProvider in …
- Very specific: line 107
Reach optional modules through their API: Use Optional<*Api>, never another module's repository directly.
- Very specific: line 136
No architecture test checks the draft guard, so add an endpoint test that a token cannot publish through a draft-capable endpoint.
- Very specific: line 150
If DistributedDataProvider lacks what you need, add it there, implement it for all three providers (Hazelcast, Redis, Local), and add a …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Server architecture gates
Artemis enforces server conventions with ArchUnit tests under src/test/java. This skill maps
server changes to those checks and explains rules whose failure messages lack context.
Run them locally
The whole architecture suite, which is what the Server Code Style job runs:
./gradlew test -DincludeTags='ArchitectureTest' -x webappThis is much faster than the full server test suite. Run it before pushing any change to
src/main/java. A violation fails both Server Code Style and Server Tests, so it is worth catching
locally.
A single class while iterating:
./gradlew test --tests ArchitectureTest -x webappWhich rules apply to what you changed
| You changed | Read |
| A service or REST resource | Transactions, persistence access, module boundaries |
| A repository | Transactions, raw JDBC |
| A DTO record | DTO conventions |
| Anything holding state across requests | Caching, distributed data |
| An entity or an association | Caching, entity conventions, column mapping |
| Anything at all in a large file | Counted gates |
| Anything that lowercases or uppercases | Case conversion |
| Anything that serializes JSON | Jackson version |
| A websocket topic or message handler | Websocket topics |
| An endpoint a coding agent should call | Endpoints opted in to access tokens |
The detail for each, with the reason and the failing rule name, is in reference/gates.md. Read
it rather than guessing; several of these rules forbid something that looks completely reasonable.
Jackson 2 must not appear in production code. Artemis serializes with Jackson 3, whose packages are
tools.jackson. Jackson 2 stays on the runtime classpath for third-party libraries that carry their own
mapper, so a com.fasterxml.jackson.databind, .core, .dataformat, .datatype, .module, .jr or
.jaxrs import still compiles — testNoJackson2InProductionCode in ArchitectureTest is what rejects it.
The one exception is com.fasterxml.jackson.annotation: jackson-annotations never moved to the
tools.jackson group, so @JsonInclude, @JsonProperty and @JsonTypeInfo stay where they are and must
not be "fixed". Mappers are immutable in Jackson 3 — derive one with JsonMapper.builder() or
rebuild(), never configure() or registerModule() on a built instance — and its exceptions are
unchecked, so a catch (IOException) no longer catches a parse failure.
Configuration lifecycle
Course and exercise settings use permanent default rows. Create courses with
CourseRepository.saveWithDefaultConfigurations; this initializes settings even when an optional module is disabled.
Every path that stores a new exercise (creation, every kind of import, copies) calls
ExerciseConfigurationService.initialize right after the first save; it inserts the team and plagiarism rows with a plain
INSERT after an unlocked existence read, and applies the request's settings in place, and nothing creates a missing row later. Programming
creation/import also persists build settings.
Use modifying queries for feature switches and settings endpoints, preserving configuration ids. Do not recreate or
remove settings when disabling a feature. Backfill existing owners with the Liquibase migration skill. See
database.
The rules most often broken
No transaction boundaries in services or controllers. @Transactional,
TransactionTemplate, and PlatformTransactionManager belong in repositories, typically on
modifying queries, and TransactionSynchronizationManager is banned outright. Enforced globally by
testTransactionBoundariesOnlyInRepositories, testNoProgrammaticTransactionManagement and
testNoTransactionSynchronization in
src/test/java/de/tum/cit/aet/artemis/shared/architecture/ArchitectureTest.java. The replacements
are a check in the WHERE clause of a @Modifying query, or explicit compensation in a catch
block.
No direct persistence access. No injected EntityManager or EntityManagerFactory, and no
JdbcClient, JdbcTemplate, or DataSource. Write the statement as a @Query on a repository,
with nativeQuery = true where there is no entity to name. Enforced by
shouldNotUseEntityManagerDirectly and shouldNotUseRawJdbcDirectly in
src/test/java/de/tum/cit/aet/artemis/shared/architecture/ArchitectureTest.java.
Two classes, RepositoryImpl and CustomPostRepositoryImpl, sit on that rule's exception list,
carrying a TODO to refactor them away. A new class doing the same thing fails the rule, because the
list is grandfathering rather than permission. Raw JDBC
has no per-class exceptions at all; only core.config may hold a DataSource.
Never touch Hazelcast or Redis directly. All cross-node state goes through
DistributedDataProvider in
src/main/java/de/tum/cit/aet/artemis/core/service/distributed/. Enforced by
src/test/java/de/tum/cit/aet/artemis/shared/architecture/DistributedDataProviderArchitectureTest.java.
The provider is configurable, so direct usage does not fail loudly, it silently loses the state.
No @Lob. A CLOB on PostgreSQL is a large object, so the value lands in pg_largeobject and the
column keeps only its id - while the long text columns here are Liquibase longtext or clob, both
text on PostgreSQL, holding the text itself. A String or a converted attribute needs no
annotation at all; for a structured value use @JdbcTypeCode(SqlTypes.JSON) over a json column.
Enforced by testNoLobAnnotation in ArchitectureTest.java.
No Hibernate second-level cache. No @Cache on entities or associations. Enforced by
testNoHibernateSecondLevelCacheAnnotation in ArchitectureTest.java. For DTO and projection
caching use Spring @Cacheable, always paired with explicit eviction.
Reach optional modules through their API. Use Optional<*Api>, never another module's
repository directly.
Never fold case without a locale. String.toLowerCase() and String.toUpperCase() use the JVM
default locale, so the same input gives a different answer depending on where the server runs. Pass
Locale.ROOT for machine-facing values and Locale.ENGLISH only where the surrounding code already
does for that kind of value. Enforced by testNoLocaleLessCaseConversion in ArchitectureTest.java,
over production and test classes both.
Every websocket destination is a declared topic. Declare a WebsocketTopic with its
WebsocketTopicAccess rule, or a WebsocketUserTopic for data of one user, as a public static final
constant of the module's web/<Module>WebsocketTopics class, and send with
websocketMessagingService.sendMessage(TOPIC.at(id), dto). A subscription to an undeclared destination
is rejected, so a topic that is sent but not declared silently reaches nobody. Clients send only to
/app/... destinations handled by @MessageMapping methods, which check the sender themselves.
Enforced by WebsocketTopicArchitectureTest in
src/test/java/de/tum/cit/aet/artemis/shared/architecture/.
JSON through records, never the tree model. Production code does not use JsonNode, ObjectNode, ArrayNode or the
other classes of tools.jackson.databind.node, and does not call readTree, valueToTree, treeToValue, createObjectNode,
createArrayNode or readValueAsTree. Model the JSON as a record and use readValue and writeValueAsString; there are no
exceptions. Enforced by JacksonTreeModelArchitectureTest in
src/test/java/de/tum/cit/aet/artemis/shared/architecture/, over production classes only.
Endpoints opted in to access tokens. Opting an endpoint in with @AllowedScopes makes it reachable by a coding agent that
holds a personal access token, so it needs an @EnforceAtLeast... annotation, DTOs only in its request body and response, an
@Operation summary, and an entry in the committed agent specification
(./gradlew generateOpenApiDocs -PopenApiGroup=agent pruneOpenApiSpec -x webapp). Exercise and lecture-unit endpoints with the
draft-date contract also call AgentDraftRules; announcements, competencies and lecture metadata are immediately visible.
No architecture test checks the draft guard, so add an endpoint test that a token cannot publish through a draft-capable endpoint.
The other rules are enforced by AllowedScopesArchitectureTest in
src/test/java/de/tum/cit/aet/artemis/shared/architecture/. See
agent access.
Before adding a cache
The default answer is not to. The bar is a measured performance gain that justifies the
eviction-correctness work, because there is no service-level transaction boundary to coordinate
eviction within a request. See documentation/docs/developer/guidelines/caching.mdx for the full
rationale, and reference/gates.md for the pattern if you do proceed.
Adding a capability to the distributed data layer
If DistributedDataProvider lacks what you need, add it there, implement it for all three providers
(Hazelcast, Redis, Local), and add a case to AbstractDistributedDataTest. That suite is what keeps
the providers in agreement. Request entry lifetimes at the call site with
getExpiringMap(name, ttl); getMap(name) rejects a per-entry TTL deliberately, because a provider
map configuration only applies to that one provider. Full guidance:
documentation/docs/developer/guidelines/distributed-data.mdx.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

