# spiculedata/saiku architecture

> Architecture diagram of the GitHub repository spiculedata/saiku, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spiculedata/saiku
- Repository: https://github.com/spiculedata/saiku

## Overview

##### Request entrypoints
Users mainly enter through `/ui/` for the SPA and `/rest/saiku/...` for API calls. The backend also exposes specialized endpoints for dashboards, administration, schema generation, AI queries, OLAP discovery, exports, sessions, and MCP-style agent access. The launcher embeds Jetty, so the app runs as a single JAR rather than a standalone app server deployment.

##### Frontend boundary
`saiku-ui` is a typed SvelteKit client that talks to backend REST APIs through a small API layer under `src/lib/api`. Its state is organized around stores for session, repository, datasources, query state, dashboards, schema cache, and schema generation. The UI is not the source of truth; it renders and edits query/model state that is persisted and executed by the backend.

##### Core OLAP query pipeline
The central backend flow is: UI or API request → REST resource in `saiku-web` → service layer in `saiku-service` → Mondrian/Calcite OLAP engine → result formatting/serialization → response back to the client. `QueryResource` / `Query2Resource` and `OlapDiscoverResource` are the main REST surfaces, while `OlapQueryService`, `ThinQueryService`, and `OlapDiscoverService` hold the execution logic.

##### Repository and datasource management
The platform stores user content, saved queries, dashboards, and datasource definitions in repository abstractions rather than directly in the UI. `FilesystemRepositoryManager` and the datasource managers in `saiku-service` are the main persistence boundary, with `saiku-web` adding security-aware wrappers for role-based access. This repository layer is also where ACLs, path handling, and seeding behavior are enforced.

##### Security and session boundary
Authentication and authorization are handled in the backend, with Spring Security configured in `saiku-webapp` and additional runtime filters in `saiku-web` for CSRF, audit logging, login rate limiting, and cleanup. Session-oriented services isolate anonymous versus authenticated usage, and datasource access can be constrained by role-aware processors. This is a hard boundary: the UI never talks directly to databases or repository storage.

##### AI query and semantic-layer APIs
A major newer subsystem is the typed AI query surface under `/rest/saiku/api/ai/*`. It exposes cube metadata, schemas, validated query requests, and structured validation errors so agents can ask questions without writing MDX. The pipeline involves schema/metadata services, request validation, query synthesis, and execution; semantic annotations on cubes feed the discovery and validation logic.

##### Schema generation pipeline
`saiku-service/src/main/java/org/saiku/service/schema/generate` is a separate end-to-end pipeline for building Mondrian schemas from JDBC metadata. The flow is: JDBC introspection → database model → inference/classification → optional LLM enrichment → draft schema / sidecar generation → delta reconciliation / application → Mondrian schema writer. The `schemagen` REST resources expose this as a sessioned workflow, so it behaves more like a guided compiler than a simple CRUD endpoint.

##### Semantic-layer authoring
`saiku-core/saiku-semantic` adds a YAML-based semantic layer that can be compiled into Mondrian-friendly structures. This is a distinct authoring boundary from the runtime OLAP engine: YAML/IR objects are parsed and compiled before reaching query execution or schema generation. It is the bridge between human-authored semantic models and the backend runtime.

##### Dashboards as a higher-level orchestration layer
Dashboards are built on top of the query and repository subsystems. The dashboard REST resources and UI components combine saved queries, filter state, tile placement, KPI configuration, and cascading filter logic. In architectural terms, dashboards are not a separate engine; they are a composition layer over saved queries plus repository-backed metadata.

##### Legacy webapp vs modern launcher
`saiku-webapp` contains the older servlet/Spring XML packaging, while `saiku-launcher` is the modern runtime wrapper that assembles the backend, serves the frontend assets, and launches Jetty. That split is important for diagramming: the launcher is the actual deployment boundary, and the webapp module is the embedded web application configuration consumed by it.

##### Operational/testing structure
The repository is organized around unit tests per subsystem and launcher-level integration tests that boot the full stack against the seeded demo environment. That test layout mirrors the runtime architecture: isolated core logic in `saiku-core`, REST wiring in `saiku-web`, and end-to-end validation through the launcher.

Main entry points: [`saiku-core/saiku-web/src/main/java/org/saiku/web/rest/SaikuJerseyApplication.java`](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/SaikuJerseyApplication.java) (REST API), [`saiku-core/saiku-service/src/main/java/org/saiku/service/olap/OlapQueryService.java`](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/olap/OlapQueryService.java) (OLAP services), [`saiku-webapp/src/main/webapp/WEB-INF/web.xml`](https://github.com/spiculedata/saiku/blob/development/saiku-webapp/src/main/webapp/WEB-INF/web.xml) (Webapp), [`saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/dashboards/DashboardResource.java`](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/dashboards/DashboardResource.java) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_saiku_launcher["Launcher<br/>java boot<br/>[SaikuLauncher.java]"]
  node_saiku_webapp["Webapp<br/>legacy servlet config<br/>[web.xml]"]
end

subgraph group_grp_frontend["Frontend"]
  node_saiku_ui["UI<br/>sveltekit app<br/>[+page.svelte]"]
  node_ui_api["API layer<br/>frontend client<br/>[http.ts]"]
  node_ui_stores["Stores<br/>ui state<br/>[session.svelte.ts]"]
  node_ui_workspace["Workspace<br/>query editor<br/>[Workspace.svelte]"]
  node_ui_dashboards["Dashboards UI<br/>composition layer"]
end

subgraph group_grp_web["Web API"]
  node_web_rest["REST API<br/>jersey resources"]
  node_web_query["Query API<br/>olap resources<br/>[QueryResource.java]"]
  node_web_ai["AI API<br/>typed query api"]
  node_web_schema["Schema API<br/>guided workflow"]
  node_web_dashboards["Dashboard API<br/>dashboard resources"]
  node_web_security["Security<br/>authn/authz"]
end

subgraph group_grp_core["Core backend"]
  node_core_olap["OLAP services<br/>execution pipeline"]
  node_core_query2["Thin model<br/>new query model<br/>[ThinQuery.java]"]
  node_core_query1["MDX model<br/>legacy query model<br/>[OlapQuery.java]"]
  node_core_result["Results<br/>cellset shaping<br/>[CellDataSet.java]"]
  node_core_repo[("Repository<br/>filesystem repo")]
  node_core_datasource[("Datasources<br/>connection management")]
  node_core_semantic["Semantic layer<br/>yaml compiler"]
  node_core_schemagen["Schema gen<br/>pipeline"]
  node_core_export["Exporters<br/>report formats<br/>[CsvExporter.java]"]
end

subgraph group_grp_assets["Assets"]
  node_assets_repo["Seed repo<br/>sample content<br/>[asdf.saiku]"]
  node_assets_seed["Demo data<br/>sample datasource<br/>[FoodMart4.xml]"]
end

node_saiku_launcher -->|"boots"| node_saiku_webapp
node_saiku_launcher -->|"serves"| node_saiku_ui
node_saiku_ui -->|"calls"| node_ui_api
node_ui_api -->|"REST calls"| node_web_rest
node_ui_stores -->|"drives"| node_ui_workspace
node_ui_stores -->|"drives"| node_ui_dashboards
node_web_rest -->|"routes"| node_web_query
node_web_rest -->|"routes"| node_web_ai
node_web_rest -->|"routes"| node_web_schema
node_web_rest -->|"routes"| node_web_dashboards
node_web_rest -->|"guards"| node_web_security
node_web_query -->|"executes"| node_core_olap
node_web_ai -->|"advises"| node_core_olap
node_web_schema -->|"orchestrates"| node_core_schemagen
node_web_dashboards -->|"loads"| node_core_repo
node_web_dashboards -->|"queries"| node_core_olap
node_core_olap -->|"uses"| node_core_query1
node_core_olap -->|"uses"| node_core_query2
node_core_olap -->|"formats"| node_core_result
node_core_result -->|"writes"| node_core_export
node_core_repo -->|"seeds"| node_assets_repo
node_core_datasource -->|"uses"| node_assets_seed
node_core_semantic -->|"feeds"| node_core_schemagen
node_core_schemagen -->|"persists"| node_core_repo
node_saiku_webapp -->|"configures"| node_web_security
node_saiku_webapp -->|"hosts"| node_web_rest

click node_saiku_launcher "https://github.com/spiculedata/saiku/blob/development/saiku-launcher/src/main/java/org/saiku/launcher/SaikuLauncher.java"
click node_saiku_webapp "https://github.com/spiculedata/saiku/blob/development/saiku-webapp/src/main/webapp/WEB-INF/web.xml"
click node_saiku_ui "https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/routes/+page.svelte"
click node_ui_api "https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/api/http.ts"
click node_ui_stores "https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/stores/session.svelte.ts"
click node_ui_workspace "https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/views/Workspace.svelte"
click node_ui_dashboards "https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/views/dashboard/DashboardEditor.svelte"
click node_web_rest "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/SaikuJerseyApplication.java"
click node_web_query "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/QueryResource.java"
click node_web_ai "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/AiQueryResource.java"
click node_web_schema "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/schemagen/SchemaGeneratorResource.java"
click node_web_dashboards "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/dashboards/DashboardResource.java"
click node_web_security "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/security/ratelimit/LoginRateLimitFilter.java"
click node_core_olap "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/olap/OlapQueryService.java"
click node_core_query2 "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/olap/query2/ThinQuery.java"
click node_core_query1 "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/olap/query/OlapQuery.java"
click node_core_result "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/olap/dto/resultset/CellDataSet.java"
click node_core_repo "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/repository/FilesystemRepositoryManager.java"
click node_core_datasource "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/datasource/DatasourceService.java"
click node_core_semantic "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-semantic/src/main/java/org/saiku/semantic/mondrian/MondrianCompiler.java"
click node_core_schemagen "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/schema/generate/session/SchemaGenOrchestrator.java"
click node_core_export "https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/util/export/CsvExporter.java"
click node_assets_repo "https://github.com/spiculedata/saiku/blob/development/saiku-repository/asdf.saiku"
click node_assets_seed "https://github.com/spiculedata/saiku/blob/development/saiku-launcher/src/main/resources/seed/FoodMart4.xml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_saiku_launcher,node_saiku_webapp toneBlue
class node_saiku_ui,node_ui_api,node_ui_stores,node_ui_workspace,node_ui_dashboards toneAmber
class node_web_rest,node_web_query,node_web_ai,node_web_schema,node_web_dashboards,node_web_security toneMint
class node_core_olap,node_core_query2,node_core_query1,node_core_result,node_core_repo,node_core_datasource,node_core_semantic,node_core_schemagen,node_core_export toneRose
class node_assets_repo,node_assets_seed toneIndigo
```

## Components

### Runtime

Deployment and app assembly boundary

- [Launcher](https://github.com/spiculedata/saiku/blob/development/saiku-launcher/src/main/java/org/saiku/launcher/SaikuLauncher.java): java boot · Embeds Jetty and assembles the runnable distribution. · `saiku-launcher/src/main/java/org/saiku/launcher/SaikuLauncher.java`
- [Webapp](https://github.com/spiculedata/saiku/blob/development/saiku-webapp/src/main/webapp/WEB-INF/web.xml): legacy servlet config · Older Spring/XML web application packaging consumed by the launcher. · `saiku-webapp/src/main/webapp/WEB-INF/web.xml`

### Frontend

SvelteKit client and UI state

- [UI](https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/routes/+page.svelte): sveltekit app · Typed SvelteKit frontend that owns presentation and local state. · `saiku-ui/src/routes/+page.svelte`
- [API layer](https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/api/http.ts): frontend client · Small client boundary for REST calls from the SvelteKit app. · `saiku-ui/src/lib/api/http.ts`
- [Stores](https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/stores/session.svelte.ts): ui state · Session, repository, datasource, query, dashboard, and schema state. · `saiku-ui/src/lib/stores/session.svelte.ts`
- [Workspace](https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/views/Workspace.svelte): query editor · Main authoring surface for queries, cellsets, and charts. · `saiku-ui/src/lib/views/Workspace.svelte`
- [Dashboards UI](https://github.com/spiculedata/saiku/blob/development/saiku-ui/src/lib/views/dashboard/DashboardEditor.svelte): composition layer · Higher-level dashboard editor and tile runtime built on saved queries. · `saiku-ui/src/lib/views/dashboard/DashboardEditor.svelte`

### Web API

REST resources, security, and servlet integration

- [REST API](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/SaikuJerseyApplication.java): jersey resources · Primary REST boundary for queries, discovery, repository, session, admin, export, AI, and schema generation. · `saiku-core/saiku-web/src/main/java/org/saiku/web/rest/SaikuJerseyApplication.java`
- [Query API](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/QueryResource.java): olap resources · MDX and thin-query entrypoints plus OLAP discovery. · `saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/QueryResource.java`
- [AI API](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/AiQueryResource.java): typed query api · Structured AI query and validation endpoints over cube metadata. · `saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/AiQueryResource.java`
- [Schema API](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/schemagen/SchemaGeneratorResource.java): guided workflow · Sessioned schema generation resource for JDBC-to-Mondrian authoring. · `saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/schemagen/SchemaGeneratorResource.java`
- [Dashboard API](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/dashboards/DashboardResource.java): dashboard resources · Repository-backed dashboard composition and filter orchestration. · `saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/dashboards/DashboardResource.java`
- [Security](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-web/src/main/java/org/saiku/web/security/ratelimit/LoginRateLimitFilter.java): authn/authz · Spring Security, CSRF, audit, and login rate limiting boundary. · `saiku-core/saiku-web/src/main/java/org/saiku/web/security/ratelimit/LoginRateLimitFilter.java`

### Core backend

OLAP execution, repository, semantic layer, exports, and schema generation

- [OLAP services](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/olap/OlapQueryService.java): execution pipeline · Query execution, discovery, async handling, and drillthrough coordination. · `saiku-core/saiku-service/src/main/java/org/saiku/service/olap/OlapQueryService.java`
- [Thin model](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/olap/query2/ThinQuery.java): new query model · Modern thin query representation and conversion utilities. · `saiku-core/saiku-service/src/main/java/org/saiku/olap/query2/ThinQuery.java`
- [MDX model](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/olap/query/OlapQuery.java): legacy query model · Older MDX-oriented query objects and serialization/deserialization. · `saiku-core/saiku-service/src/main/java/org/saiku/olap/query/OlapQuery.java`
- [Results](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/olap/dto/resultset/CellDataSet.java): cellset shaping · Cellset DTOs, formatters, hierarchical/flattened rendering, and Arrow writers. · `saiku-core/saiku-service/src/main/java/org/saiku/olap/dto/resultset/CellDataSet.java`
- [Repository](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/repository/FilesystemRepositoryManager.java): filesystem repo · Filesystem-backed saved content, ACLs, path handling, and repository objects. · `saiku-core/saiku-service/src/main/java/org/saiku/repository/FilesystemRepositoryManager.java`
- [Datasources](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/datasource/DatasourceService.java): connection management · Datasource definitions, connection factories, and security-aware access control. · `saiku-core/saiku-service/src/main/java/org/saiku/service/datasource/DatasourceService.java`
- [Semantic layer](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-semantic/src/main/java/org/saiku/semantic/mondrian/MondrianCompiler.java): yaml compiler · YAML semantic authoring compiled into Mondrian-friendly structures. · `saiku-core/saiku-semantic/src/main/java/org/saiku/semantic/mondrian/MondrianCompiler.java`
- [Schema gen](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/schema/generate/session/SchemaGenOrchestrator.java): pipeline · JDBC introspection, inference, enrichment, reconciliation, and Mondrian schema writing. · `saiku-core/saiku-service/src/main/java/org/saiku/service/schema/generate/session/SchemaGenOrchestrator.java`
- [Exporters](https://github.com/spiculedata/saiku/blob/development/saiku-core/saiku-service/src/main/java/org/saiku/service/util/export/CsvExporter.java): report formats · CSV, Excel, PDF, SVG/HTML-derived, and Arrow export paths. · `saiku-core/saiku-service/src/main/java/org/saiku/service/util/export/CsvExporter.java`

### Assets

Seeded repository content and sample data

- [Seed repo](https://github.com/spiculedata/saiku/blob/development/saiku-repository/asdf.saiku): sample content · Seeded repository objects and sample queries distributed with the launcher. · `saiku-repository/asdf.saiku`
- [Demo data](https://github.com/spiculedata/saiku/blob/development/saiku-launcher/src/main/resources/seed/FoodMart4.xml): sample datasource · FoodMart and other seeded data/schema assets used by demo and integration tests. · `saiku-launcher/src/main/resources/seed/FoodMart4.xml`

## Connections

- Launcher → Webapp: boots · Launcher assembles the legacy webapp configuration into the runnable Jetty deployment.
- Launcher → UI: serves · Launcher exposes the SvelteKit frontend assets with the backend runtime.
- UI → API layer: calls · UI components use the typed API layer for backend communication.
- API layer → REST API: REST calls · Frontend API layer talks to the Jersey REST surface.
- Stores → Workspace: drives · Application state feeds the main query editor and visualization surface.
- Stores → Dashboards UI: drives · Store state feeds dashboard editing and tile rendering.
- REST API → Query API: routes · The REST application exposes the main OLAP query and discovery endpoints.
- REST API → AI API: routes · The REST application exposes typed AI query endpoints.
- REST API → Schema API: routes · The REST application exposes schema generation workflow endpoints.
- REST API → Dashboard API: routes · The REST application exposes dashboard management endpoints.
- REST API → Security: guards · Security, audit, CSRF, and rate-limiting wrap the web surface.
- Query API → OLAP services: executes · Query resources delegate to OLAP execution and discovery services.
- AI API → OLAP services: advises · AI query requests use cube metadata and OLAP execution underneath.
- Schema API → Schema gen: orchestrates · Schema generation API drives the guided compiler-like workflow.
- Dashboard API → Repository: loads · Dashboards are composed from repository-backed saved content.
- Dashboard API → OLAP services: queries · Dashboard tiles ultimately execute OLAP queries.
- OLAP services → MDX model: uses · Legacy query execution still understands MDX-oriented query objects.
- OLAP services → Thin model: uses · Newer execution and validation flows use the thin query model.
- OLAP services → Results: formats · Execution results are normalized into cellsets and rendered formats.
- Results → Exporters: writes · Result structures feed downstream CSV, Excel, PDF, and Arrow exporters.
- Repository → Seed repo: seeds · Repository storage is populated with bundled sample queries and content.
- Datasources → Demo data: uses · Seeded datasource and cube definitions underpin demo and integration flows.
- Semantic layer → Schema gen: feeds · Semantic YAML structures inform schema generation and OLAP modeling.
- Schema gen → Repository: persists · Generated drafts, sidecars, and schema artifacts are stored in the repository boundary.
- Webapp → Security: configures · Legacy Spring/XML packaging provides servlet and security configuration.
- Webapp → REST API: hosts · The older webapp module hosts the REST application wiring consumed by the launcher.
