Skip to main content

Backend Architecture

The backend follows a deliberate hexagonal / ports-and-adapters layout. The dependency direction is always outer → inner:

┌──────────────────────────────────────────────────────────┐
│ api/controller/ ← HTTP boundary (Spring MVC) │
│ api/dto/ ← request/response shapes │
│ │ │
│ ▼ │
│ services/<feature>/ ← use cases (interfaces) + │
│ their implementations │
│ │ │
│ ▼ │
│ database/DatabasePort ← port interface │
│ database/inmemory/ ← active dataset store │
│ database/implementations/http/ ← Fuseki connection │
└──────────────────────────────────────────────────────────┘

Use case interfaces​

Every action exposed by the application is a one-method *UseCase interface, e.g.:

public interface ListDatasetsUseCase {
List<String> listDatasets();
}

A controller depends only on the use case interface; a service implements one or many use cases. This is a deliberate design choice — it keeps controllers small, makes individual operations easy to test, and lets services compose multiple ports without becoming god classes.

Services​

Services live under services/<feature>/ and typically implement multiple use cases when they share state, repositories, or transaction boundaries. The services/select/QueryDatasetService is a good representative example — it implements GetDatasetSchemaUseCase, ListGraphsUseCase, ListPrefixesUseCase, and ListDatasetsUseCase, all of which need the same DatabasePort.

The database port​

DatabasePort is the only direct contact with the active dataset store. Runtime datasets live in the in-memory adapter; Fuseki is used through the database connection and snapshot port when snapshots are created or loaded:^

  • database/implementations/http — talks to Fuseki over the SPARQL 1.1 protocol + Graph Store Protocol for snapshot operations.

The in-memory path (database/inmemory) is used heavily in tests and as the per-session working buffer for uploaded datasets and edits.

Its contents (graphs, custom diagrams, layout, namespaces) are reachable only through a workspace transaction, so that a change touching several of them commits or rolls back as a whole and becomes one entry in the workspace changelog:

try (var transaction = databasePort.beginTransaction(datasetName, ReadWrite.WRITE)) {
var ctx = transaction.graph(graphUri);
// … edit ctx.getRdfGraph(), transaction.diagrams(), transaction.layout() …
transaction.commit("Deleted class \"Breaker\"");
}

A commit message is the text the changelog and the undo toast show, so it is written for the person who made the change: past tense, and naming what was changed rather than identifying it. services/ChangeDescriptions builds those names. commitWithoutHistory() stores a change the user did not ask for, such as the layout a diagram gets the first time it is opened, without offering it as an undo step.

REST controllers​

Controllers are thin and follow a strict skeleton:

@RestController
@RequestMapping("api/datasets")
@RequiredArgsConstructor
public class DatasetRESTController {

private static final Logger logger = LoggerFactory.getLogger(...);

private final ListDatasetsUseCase listDatasetsUseCase;
private final DeleteDatasetUseCase deleteDatasetUseCase;

@Operation(summary = "...", description = "...", tags = {...})
@GetMapping
public List<String> listDatasets(...) {
logger.info("Received GET request: ...");
var result = listDatasetsUseCase.listDatasets();
logger.info("Sending response to GET ...");
return result;
}
}

Conventions worth knowing:

  • One controller per resource path tier. api/datasets, api/datasets/{name}/graphs, api/datasets/{name}/graphs/{uri}/classes, etc. Controllers do not span tiers.
  • Always @Operation annotated — Swagger UI is part of the public deliverable.
  • Always log on receive and on respond, with the originating URL, dataset, and graph names where applicable. Audit log style.
  • Use cases are constructor-injected via @RequiredArgsConstructor (Lombok). No field injection.
  • Read the Origin header into a parameter called originURL. It is logged but never used for authorisation — auth lives outside the application.

DTOs and mapping​

DTOs live under api/dto/ and are organised by feature (attributes/, associations/, enumentries/, migration/, ontology/, packages/, rendering/). They are flat data carriers — Lombok @Value or @Data — with no behaviour.

MapStruct generates DTO ↔ domain mappers. When you add a new DTO, also add the corresponding *Mapper interface and let MapStruct generate the implementation. The annotation processor runs as part of mvn compile.

Exception handling​

Domain exceptions live in exception/<area>/ and are translated to HTTP responses by handlers in exception/handlers/. A new exception that needs a non-500 response must have a handler — there is no fallback that turns arbitrary exceptions into 4xx.

SPARQL templates​

Parameterised SPARQL queries live in src/main/resources/sparql-templates/ and are loaded by classpath utility methods. The migration use cases use them heavily — see sparql-templates/migration/*.sparql for the templates that the wizard composes into the final UPDATE script. Keep templates here rather than inline string concatenation in Java.

Generated artefacts​

The migration wizard turns one list of SemanticClassChange objects into two artefacts. Each has a builder interface with a single implementation in services/schemamigration/artifacts/:

  • MigrationScriptBuilder → SparqlMigrationBuilder — the SPARQL UPDATE script, composed from the templates above. See Working with RDF, SHACL, and SPARQL.
  • MigrationReportBuilder → MarkdownMigrationReportBuilder — the Markdown migration report, in a summary and a detailed variant. SchemaMigrationService prepends the validation reports of both schemas via SchemaValidationReportToMarkdownService before handing the changes over.

The report renders field changes as sentences through a switch over SemanticFieldChangeType, so a new change type needs a case there — without one it silently renders as an empty line. Keep the two builders in step: a change that migrates data but never appears in the report is invisible to whoever reviews the migration.