Frontend Architecture
Stack
- SvelteKit (Svelte 5 with runes —
$state,$derived,$effect,$props,$bindable). - Vite for build and dev server.
- Tailwind CSS for styling, with project-specific design tokens (CSS variables) in
src/lib/styles/. - bits-ui for headless dialog, menubar, and dropdown primitives, wrapped in project-local components under
src/lib/components/bitsui/. - SvelteFlow for diagram rendering, with elkjs for auto-layout.
- Mermaid for the deprecated alternative renderer, which is no longer developed.
- CodeMirror 6 with
codemirror-lang-turtlefor the TTL editors. - Asciidoctor.js for rendering class comments.
- Vitest for unit tests, jsdom for the DOM environment.
Routes
SvelteKit's filesystem routing is used straightforwardly:
/ → Homepage (routes/+page.svelte)
/mainpage → Main editor (left tree + diagram + right class editor)
/changelog → Edit history view
/compare → Compare results view
/migrate → 7-step migration wizard
/shacl/... → SHACL views
The editor listens to URL parameters ?dataset=...&graph=...&package=... to support deep links.
Reactive models
A central pattern: every editable domain object has a reactive wrapper in lib/models/reactive/models/ (e.g. reactive-class.svelte.js, reactive-namespace.svelte.js, reactive-ontology.svelte.js). These wrappers:
- Hold the original DTO and a working copy.
- Track
isModified,isValid, and per-field violations as$derivedrunes. - Expose
save(),reset(), and field accessors. - Drive the inline validation visible in dialogs.
DTO ↔ reactive object mapping lives in lib/models/reactive/mapper/. Whenever you add a new field to the backend that the frontend needs to edit, the chain to update is:
- Backend DTO.
- Frontend type in
lib/models/dto/. - Reactive wrapper in
lib/models/reactive/models/. - DTO ↔ reactive mapper.
- UI component that exposes the field.
Validity rules
lib/models/reactive/validity-rules/validityFunctions.js is the single home for cross-cutting validation (label uniqueness, prefix uniqueness, valid IRIs, valid NCNames, etc.). Reuse what's there before adding a new function.
Backend communication
Communication with the backend happens via an automatically generated client, generated by the hey-api plugin. The client methods can then either be called directly from the components or accessed through a store, which handles caching, logging and notifications.
The client lives in src/lib/api/generated, is git-ignored, and is produced by npm run api:generate from the committed frontend/openapi.json contract. Generate it before running or building the frontend, and regenerate it whenever the contract changes — see Overview & Setup.
The generated client and store methods that mutate objects return a Response object that contains data and error. Store getters return the objects directly, or null in case of an error.
Shared state
lib/sharedState.svelte.js exports cross-component reactive state, primarily:
editorState.selectedDataset/selectedGraph/selectedPackageUUID/selectedClassUUIDforceReloadTrigger— a "kick everything to refresh" signal used after destructive actionscompareState,migrationState— wizard state passed across pages
Use these instead of inventing per-component prop drilling for global selections.
Diagram interaction
The SvelteFlow diagram lives in lib/rendering/svelteflow/. Its node and edge components are rendered by SvelteFlow and receive no props from the diagram, so state they share with it is kept in small modules under interaction/ instead, for example labelHighlight.svelte.js or propertyInteraction.svelte.js (the marked property, the property context menu, and the modifier keys that make properties unclickable).
A property opened from the diagram is requested through lib/propertyEditorRequest.svelte.js and answered by routes/mainpage/classEditor/PropertyEditorHost.svelte, which shows the attribute, association, or enum entry editor without the class editor. Those editors read everything through the classEditor context, which both the class editor and the host build with class-editor-context.js. When the class editor already holds the class, the host uses that class instead of loading a second copy, so the two editors share one unsaved state.
To identify a property, the rendering DTOs carry the UUID of every attribute, association end, and enum entry, and every edge label carries associationEndUUID. That one differs from identifiedObjectUUID, the key label positions are stored under, in merged diagrams. The owning class is resolved to the schema a property lives in, so merged class UUIDs work as well.
Edges are drawn as polylines through their edge points (components/edge/PolylineEdge.svelte, geometry in edgeUtils.ts): the docking points that pin the ends of an edge to the class border, and the bend points in between. The backend delivers the stored edge points of every edge, which diagram/diagramElements.js flattens. The edge points are edited by interaction/edgePoints.svelte.js (context menu, Ctrl+Q and Ctrl+Shift+Q) and by the handles in EdgePointHandles.svelte; pure point operations live in interaction/edgePointOperations.js. interaction/edgeLayoutPersistence.js saves an edge once it is deselected, holds edges back while a class or a point is dragged, sends the requests of one edge one after another, and flushes unsaved edges on pagehide. The automatic layout in layout/elkLayout.js (ELK Layered, in a web worker) runs only when every class sits at (0,0) or when Reset Layout is clicked.
Svelte script ordering
The repository enforces a specific script-block ordering (imports → props → constants → state → derived → effects → lifecycle → functions). The full rationale and ESLint rule are in frontend/docs/script-structure.md. The custom rule lives at frontend/eslint-rules/rules/svelte-script-order/. When in doubt, run npm run format and follow whatever the auto-fixer produces.
Custom ESLint rules
Three custom rules ship with the project:
copyright-header— enforces the Apache 2.0 header on every source file.svelte-file-structure— order of<script>, markup,<style>.svelte-script-order— order inside<script>blocks.
If you write a new file, the auto-fixer (npm run format) inserts the header for you.