How spiculedata/saiku works
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: SaikuJerseyApplication.java REST API · OlapQueryService.java OLAP services · web.xml Webapp · DashboardResource.java Dashboard API
Components 24
Runtime
Deployment and app assembly boundary
Frontend
SvelteKit client and UI state
- UI · Typed SvelteKit frontend that owns presentation and local state.
saiku-ui/src/routes/+page.svelte - API layer · Small client boundary for REST calls from the SvelteKit app.
saiku-ui/src/lib/api/http.ts - Stores · Session, repository, datasource, query, dashboard, and schema state.
saiku-ui/src/lib/stores/session.svelte.ts - Workspace · Main authoring surface for queries, cellsets, and charts.
saiku-ui/src/lib/views/Workspace.svelte - Dashboards UI · 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 · 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 · MDX and thin-query entrypoints plus OLAP discovery.
saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/QueryResource.java - AI 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 · 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 · Repository-backed dashboard composition and filter orchestration.
saiku-core/saiku-web/src/main/java/org/saiku/web/rest/resources/dashboards/DashboardResource.java - Security · 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 · Query execution, discovery, async handling, and drillthrough coordination.
saiku-core/saiku-service/src/main/java/org/saiku/service/olap/OlapQueryService.java - Thin model · Modern thin query representation and conversion utilities.
saiku-core/saiku-service/src/main/java/org/saiku/olap/query2/ThinQuery.java - MDX model · Older MDX-oriented query objects and serialization/deserialization.
saiku-core/saiku-service/src/main/java/org/saiku/olap/query/OlapQuery.java - Results · Cellset DTOs, formatters, hierarchical/flattened rendering, and Arrow writers.
saiku-core/saiku-service/src/main/java/org/saiku/olap/dto/resultset/CellDataSet.java - Repository · Filesystem-backed saved content, ACLs, path handling, and repository objects.
saiku-core/saiku-service/src/main/java/org/saiku/repository/FilesystemRepositoryManager.java - Datasources · Datasource definitions, connection factories, and security-aware access control.
saiku-core/saiku-service/src/main/java/org/saiku/service/datasource/DatasourceService.java - Semantic layer · YAML semantic authoring compiled into Mondrian-friendly structures.
saiku-core/saiku-semantic/src/main/java/org/saiku/semantic/mondrian/MondrianCompiler.java - Schema gen · 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 · 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
Connections 26
- 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.