# tencentmusic/supersonic architecture

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

- Interactive diagram: https://gitdiagram.com/tencentmusic/supersonic
- Repository: https://github.com/tencentmusic/supersonic

## Overview

1. **Repository shape**
   - This is a Maven multi-module monorepo with three major product surfaces: **Headless BI**, **Chat BI**, and **Auth**, plus shared libraries, launchers, and a separate webapp workspace.
   - The Java backend is split by domain boundaries rather than by technical layers alone, and the frontend is split into an admin-style app and an embeddable chat SDK.

2. **Top-level runtime entrypoints**
   - `launchers/headless`, `launchers/chat`, and `launchers/standalone` are the packaging/runtime entrypoints.
   - `standalone` is the demo distribution that bundles the semantic layer and chat flows together with sample configs, H2/MySQL/Postgres SQL seeds, HanLP dictionaries, and OpenSearch index templates.
   - Docker and CI workflows indicate the project is intended to run as containerized services as well as local Java processes.

3. **Shared foundation: `common/`**
   - `common` contains the cross-cutting infrastructure used by both Headless and Chat:
     - SQL parsing and rewriting utilities based on Calcite and JSqlParser.
     - Configuration, threading, logging, JSON, HTTP, encryption, retry, and context utilities.
     - Shared domain objects for chat models, embeddings, semantic/query abstractions, and return codes.
     - Model/provider integrations for LLMs and embeddings, including OpenAI, LocalAI, Dify, Ollama, in-memory, and vector store adapters.
   - This module is the main boundary for reusable platform behavior.

4. **Headless BI core (`headless/core`)**
   - This is the semantic-query engine: it translates structured or semantic requests into executable SQL.
   - Key subsystems:
     - **DB adaptors** for dialect-specific behavior across MySQL, Postgres, ClickHouse, Trino, Presto, Oracle, HANA, H2, Kyuubi, DuckDB, and StarRocks.
     - **Query executor** and accelerator layer for executing and optimizing generated SQL.
     - **Translator/parser** layer that turns semantic objects into SQL, with optimizer stages like dialect adjustment and result limiting.
     - **Cache** for query results and semantic computation reuse.
   - This module is the core boundary between semantic intent and physical data access.

5. **Headless BI server (`headless/server`)**
   - This is the product-facing semantic layer service: REST controllers, application services, repositories, and MyBatis persistence.
   - It owns the metadata lifecycle for **apps, databases, datasets, models, metrics, dimensions, tags, query rules, dictionaries, and stats**.
   - It also includes:
     - listeners for embedding and dictionary refreshes,
     - scheduled tasks for dictionary reload and meta embedding,
     - YAML/model builders and converters that map persisted metadata into semantic structures.
   - In architecture terms, this is the authoritative metadata and governance service for the semantic model.

6. **Chat BI backend (`chat/server`)**
   - This is the conversational query pipeline.
   - The flow is organized as:
     - REST controllers receive chat/config/plugin/memory requests.
     - Services coordinate chat state, query parsing, execution, configuration, statistics, and agent/plugin management.
     - Parsers choose between **rule-based**, **plain text**, **NL2SQL**, and **NL2Plugin** paths.
     - Executors run SQL, plugin calls, or plain-text responses.
     - Processors post-process parse and execution results for formatting, recommendation, metric logic, and interpretation.
   - This module is the orchestration layer that turns user conversation into actionable query results.

7. **Chat knowledge, memory, and plugin subsystems**
   - `chat/server` is not just a chat UI backend; it has its own internal knowledge pipeline.
   - **Knowledge / schema mapping**: builds searchable representations of datasets, dimensions, metrics, values, and aliases; supports embedding recall and keyword/HanLP-based matching.
   - **Memory**: stores historical conversational trajectories and review status for reuse in prompting and retrieval.
   - **Plugins**: modelled as first-class tools with managers, recognizers, events, and tool configs; they let an LLM route a query to a third-party capability instead of SQL.
   - These are the key AI-facing extension points on the Chat side.

8. **Authentication and authorization**
   - `auth/api` defines the shared auth contracts for user and access-control operations.
   - `auth/authentication` implements user identity retrieval, token handling, interceptors, and strategy selection (for example header-based or fake user strategies).
   - `auth/authorization` implements group and resource authorization APIs.
   - The repo’s auth boundary is separate from the semantic/chat domains, but its outputs feed the rest of the platform through request context and permission checks.

9. **Web applications (`webapp/`)**
   - `supersonic-fe` is the main management console:
     - semantic model authoring,
     - datasets, metrics, dimensions, domains, tags, query rules, system settings,
     - login and user administration,
     - graph/canvas-style modeling pages.
   - `chat-sdk` is a reusable embeddable chat component library with conversation views, result renderers, charts, and recommendation UI.
   - This split suggests two distinct frontend consumers: operators/engineers in the admin app, and end-users/integrators through the SDK.

10. **Data stores and external integrations**
   - Persistence is relational and ORM-based, using MyBatis mappers plus repository/service layers.
   - The repo also includes OpenSearch resources for chat memory and meta collections, and vector-store abstractions for embedding retrieval.
   - External AI services and local models are pluggable rather than hard-coded, which is important to the architecture: the system can swap LLM providers, embedding models, and retrieval stores without changing the core query flow.

11. **End-to-end data flow**
   - In Headless BI, metadata is curated in the semantic layer, persisted, and exposed through APIs; the core translator then converts semantic requests into dialect-aware SQL for the target database.
   - In Chat BI, user text enters the chat backend, is mapped against semantic knowledge and memory, parsed into semantic intent, corrected if needed, translated to SQL or routed to a plugin, then executed and formatted back to the UI.
   - The two halves are intentionally coupled through the semantic model: chat depends on headless-curated metadata for grounding, and headless benefits from chat-generated access patterns and recommendations.

12. **Operational and build boundaries**
   - CI/CD, Docker, assembly scripts, and launcher modules indicate the project is designed to ship as a packaged Java platform with multiple deployable profiles.
   - Test coverage is split by module and includes parser, translator, semantic modeling, and service-level tests, reflecting the system’s emphasis on correctness in SQL generation and metadata handling.

Main entry points: [`chat/server`](https://github.com/tencentmusic/supersonic/tree/master/chat/server) (Chat server), [`headless/server`](https://github.com/tencentmusic/supersonic/tree/master/headless/server) (Headless server), [`common`](https://github.com/tencentmusic/supersonic/tree/master/common) (Common foundation), [`auth/api`](https://github.com/tencentmusic/supersonic/tree/master/auth/api) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & packaging"]
  node_launchers_headless["Headless launcher<br/>spring boot entrypoint"]
  node_launchers_chat["Chat launcher<br/>spring boot entrypoint"]
  node_launchers_standalone["Standalone demo<br/>demo distribution"]
  node_launchers_common["Launcher common<br/>spring glue"]
end

subgraph group_platform["Backend platform"]
  node_common_platform["Common foundation<br/>shared platform lib"]
  node_auth_api["Auth API<br/>auth contracts"]
  node_auth_authn["Authn service<br/>identity service"]
  node_auth_authz["Authz service<br/>access control"]
  node_headless_api["Headless API<br/>semantic contracts"]
  node_headless_core["Semantic core<br/>sql translation engine"]
  node_headless_server["Headless server<br/>metadata service"]
  node_headless_chat["Headless chat<br/>chat-grounding layer"]
  node_chat_api["Chat API<br/>chat contracts"]
  node_chat_server["Chat server<br/>conversational pipeline"]
end

subgraph group_frontend["Web apps"]
  node_webapp_supersonic_fe["Supersonic FE<br/>admin web app"]
  node_webapp_chat_sdk["Chat SDK<br/>embeddable UI lib"]
end

node_launchers_headless -->|"starts"| node_headless_server
node_launchers_headless -->|"packages"| node_headless_core
node_launchers_headless -->|"uses"| node_auth_authn
node_launchers_headless -->|"uses"| node_auth_authz
node_launchers_chat -->|"starts"| node_chat_server
node_launchers_chat -->|"grounds on"| node_headless_server
node_launchers_chat -->|"uses"| node_auth_authn
node_launchers_standalone -->|"bundles"| node_headless_server
node_launchers_standalone -->|"bundles"| node_chat_server
node_launchers_standalone -->|"bundles"| node_headless_chat
node_launchers_standalone -->|"bundles"| node_common_platform
node_launchers_common -->|"configures"| node_common_platform
node_headless_server -->|"implements"| node_headless_api
node_headless_server -->|"delegates to"| node_headless_core
node_headless_server -->|"depends on"| node_common_platform
node_headless_chat -->|"consumes"| node_headless_api
node_headless_chat -->|"executes via"| node_headless_core
node_headless_chat -->|"depends on"| node_common_platform
node_chat_server -->|"implements"| node_chat_api
node_chat_server -->|"reads metadata"| node_headless_server
node_chat_server -->|"depends on"| node_common_platform
node_chat_server -->|"uses"| node_auth_api
node_chat_server -->|"uses"| node_auth_authn
node_chat_server -->|"uses"| node_auth_authz
node_auth_authn -->|"implements"| node_auth_api
node_auth_authz -->|"implements"| node_auth_api
node_webapp_supersonic_fe -->|"calls"| node_headless_server
node_webapp_supersonic_fe -->|"authenticates via"| node_auth_api
node_webapp_chat_sdk -->|"calls"| node_chat_server
node_webapp_chat_sdk -->|"reads model data"| node_headless_server
node_common_platform -.->|"shares context with"| node_auth_api
node_common_platform -.->|"supplies"| node_headless_core
node_common_platform -.->|"supplies"| node_chat_server

click node_launchers_headless "https://github.com/tencentmusic/supersonic/tree/master/launchers/headless"
click node_launchers_chat "https://github.com/tencentmusic/supersonic/tree/master/launchers/chat"
click node_launchers_standalone "https://github.com/tencentmusic/supersonic/tree/master/launchers/standalone"
click node_launchers_common "https://github.com/tencentmusic/supersonic/tree/master/launchers/common"
click node_common_platform "https://github.com/tencentmusic/supersonic/tree/master/common"
click node_auth_api "https://github.com/tencentmusic/supersonic/tree/master/auth/api"
click node_auth_authn "https://github.com/tencentmusic/supersonic/tree/master/auth/authentication"
click node_auth_authz "https://github.com/tencentmusic/supersonic/tree/master/auth/authorization"
click node_headless_api "https://github.com/tencentmusic/supersonic/tree/master/headless/api"
click node_headless_core "https://github.com/tencentmusic/supersonic/tree/master/headless/core"
click node_headless_server "https://github.com/tencentmusic/supersonic/tree/master/headless/server"
click node_headless_chat "https://github.com/tencentmusic/supersonic/tree/master/headless/chat"
click node_chat_api "https://github.com/tencentmusic/supersonic/tree/master/chat/api"
click node_chat_server "https://github.com/tencentmusic/supersonic/tree/master/chat/server"
click node_webapp_supersonic_fe "https://github.com/tencentmusic/supersonic/tree/master/webapp/packages/supersonic-fe"
click node_webapp_chat_sdk "https://github.com/tencentmusic/supersonic/tree/master/webapp/packages/chat-sdk"

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_launchers_headless,node_launchers_chat,node_launchers_standalone,node_launchers_common toneBlue
class node_common_platform,node_auth_api,node_auth_authn,node_auth_authz,node_headless_api,node_headless_core,node_headless_server,node_headless_chat,node_chat_api,node_chat_server toneAmber
class node_webapp_supersonic_fe,node_webapp_chat_sdk toneMint
```

## Components

### Runtime & packaging

Deployable launchers, assembly, Docker, and build scripts.

- [Headless launcher](https://github.com/tencentmusic/supersonic/tree/master/launchers/headless): spring boot entrypoint · Packaging/runtime entrypoint for the headless BI service. · `launchers/headless`
- [Chat launcher](https://github.com/tencentmusic/supersonic/tree/master/launchers/chat): spring boot entrypoint · Packaging/runtime entrypoint for the chat BI service. · `launchers/chat`
- [Standalone demo](https://github.com/tencentmusic/supersonic/tree/master/launchers/standalone): demo distribution · Bundled demo runtime with semantic, chat, sample data, and search resources. · `launchers/standalone`
- [Launcher common](https://github.com/tencentmusic/supersonic/tree/master/launchers/common): spring glue · Shared Spring/web configuration used by launcher modules. · `launchers/common`

### Backend platform

Shared backend modules for auth, common services, semantic BI, and chat BI.

- [Common foundation](https://github.com/tencentmusic/supersonic/tree/master/common): shared platform lib · Cross-cutting utilities, shared domain objects, model/provider adapters, SQL parsing, and embedding store abstractions. · `common`
- [Auth API](https://github.com/tencentmusic/supersonic/tree/master/auth/api): auth contracts · Shared authentication and authorization interfaces, requests, responses, and context helpers. · `auth/api`
- [Authn service](https://github.com/tencentmusic/supersonic/tree/master/auth/authentication): identity service · User identity, token handling, interceptors, and strategy-based authentication implementation. · `auth/authentication`
- [Authz service](https://github.com/tencentmusic/supersonic/tree/master/auth/authorization): access control · Group and resource authorization service. · `auth/authorization`
- [Headless API](https://github.com/tencentmusic/supersonic/tree/master/headless/api): semantic contracts · Semantic-layer request/response model for apps, datasets, metrics, dimensions, rules, and queries. · `headless/api`
- [Semantic core](https://github.com/tencentmusic/supersonic/tree/master/headless/core): sql translation engine · Dialect-aware semantic query translation, DB adaptors, query execution, optimization, and cache. · `headless/core`
- [Headless server](https://github.com/tencentmusic/supersonic/tree/master/headless/server): metadata service · Authoritative semantic metadata service with REST APIs, persistence, builders, listeners, and scheduled refresh tasks. · `headless/server`
- [Headless chat](https://github.com/tencentmusic/supersonic/tree/master/headless/chat): chat-grounding layer · Semantic chat pipeline for knowledge mapping, parsing, correction, and query construction on top of the headless model. · `headless/chat`
- [Chat API](https://github.com/tencentmusic/supersonic/tree/master/chat/api): chat contracts · Chat requests, responses, memory states, recommendations, and parsing contracts. · `chat/api`
- [Chat server](https://github.com/tencentmusic/supersonic/tree/master/chat/server): conversational pipeline · Conversational orchestration layer with controllers, services, parsers, executors, processors, memory, knowledge, and plugins. · `chat/server`

### Web apps

Management console and embeddable chat SDK.

- [Supersonic FE](https://github.com/tencentmusic/supersonic/tree/master/webapp/packages/supersonic-fe): admin web app · Management console for semantic modeling, permissions, login, system settings, and graph-based authoring. · `webapp/packages/supersonic-fe`
- [Chat SDK](https://github.com/tencentmusic/supersonic/tree/master/webapp/packages/chat-sdk): embeddable UI lib · Reusable chat component library for conversation, results, charts, recommendations, and agent UI. · `webapp/packages/chat-sdk`

## Connections

- Headless launcher → Headless server: starts · Bootstraps the headless semantic service.
- Headless launcher → Semantic core: packages · Includes the semantic translation engine.
- Headless launcher → Authn service: uses · Wires authentication into the service runtime.
- Headless launcher → Authz service: uses · Wires authorization checks into the service runtime.
- Chat launcher → Chat server: starts · Bootstraps the conversational service.
- Chat launcher → Headless server: grounds on · Chat depends on curated semantic metadata.
- Chat launcher → Authn service: uses · Wires authentication into the service runtime.
- Standalone demo → Headless server: bundles · Demo distribution includes semantic layer resources.
- Standalone demo → Chat server: bundles · Demo distribution includes chat flows and config.
- Standalone demo → Headless chat: bundles · Includes headless chat and semantic-query demos.
- Standalone demo → Common foundation: bundles · Ships shared platform runtime and resources.
- Launcher common → Common foundation: configures · Provides shared Spring/web wiring for launchers.
- Headless server → Headless API: implements · Serves the semantic-layer contract.
- Headless server → Semantic core: delegates to · Uses semantic translation and execution core.
- Headless server → Common foundation: depends on · Uses shared utilities, models, and integrations.
- Headless chat → Headless API: consumes · Builds semantic queries from headless contracts.
- Headless chat → Semantic core: executes via · Turns semantic intent into database SQL.
- Headless chat → Common foundation: depends on · Uses shared SQL, LLM, and retrieval infrastructure.
- Chat server → Chat API: implements · Serves the conversational contract.
- Chat server → Headless server: reads metadata · Relies on semantic model, datasets, and dictionaries.
- Chat server → Common foundation: depends on · Uses shared models, tools, and model provider adapters.
- Chat server → Auth API: uses · Consumes user and permission context.
- Chat server → Authn service: uses · Depends on authenticated user identity.
- Chat server → Authz service: uses · Applies access-control checks to chat operations.
- Authn service → Auth API: implements · Provides identity and token services for the auth contract.
- Authz service → Auth API: implements · Provides authorization services for the auth contract.
- Supersonic FE → Headless server: calls · Management console drives semantic metadata APIs.
- Supersonic FE → Auth API: authenticates via · Login and user administration flow through auth APIs.
- Chat SDK → Chat server: calls · Embeddable UI consumes chat and recommendation APIs.
- Chat SDK → Headless server: reads model data · Renders semantic/query results grounded in headless metadata.
- Common foundation → Auth API: shares context with · Shared user, permission, and return-code types.
- Common foundation → Semantic core: supplies · Provides SQL parsing, dialect, and model-provider utilities.
- Common foundation → Chat server: supplies · Provides embeddings, LLM adapters, and retrieval utilities.
