agentleFS
ls1intumls1intum/Artemis/skills/server-arch-gates/SKILL.md

server-arch-gates

Skill829 starsChanged 3 years agoMITView on GitHub

Apply Artemis architecture rules when changing server Java or diagnosing an ArchUnit failure.

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
  1. Very specific:

    Every path that stores a new exercise (creation, every kind of import, copies) calls ExerciseConfigurationService.initialize right after …

    line 61
  2. Distinctive:

    Use modifying queries for feature switches and settings endpoints, preserving configuration ids.

    line 65
  3. Very specific:

    No direct persistence access: No injected EntityManager or EntityManagerFactory, and no JdbcClient, JdbcTemplate, or DataSource.

    line 80
  4. Very specific:

    Never touch Hazelcast or Redis directly: All cross-node state goes through DistributedDataProvider in …

    line 91
  5. Very specific:

    Reach optional modules through their API: Use Optional<*Api>, never another module's repository directly.

    line 107
  6. Very specific:

    No architecture test checks the draft guard, so add an endpoint test that a token cannot publish through a draft-capable endpoint.

    line 136
  7. Very specific:

    If DistributedDataProvider lacks what you need, add it there, implement it for all three providers (Hazelcast, Redis, Local), and add a …

    line 150

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 webapp

This 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 webapp

Which rules apply to what you changed

You changedRead
A service or REST resourceTransactions, persistence access, module boundaries
A repositoryTransactions, raw JDBC
A DTO recordDTO conventions
Anything holding state across requestsCaching, distributed data
An entity or an associationCaching, entity conventions, column mapping
Anything at all in a large fileCounted gates
Anything that lowercases or uppercasesCase conversion
Anything that serializes JSONJackson version
A websocket topic or message handlerWebsocket topics
An endpoint a coding agent should callEndpoints 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.