Architecture
Architecture overview
The subsystem map — apps, shared packages, and how they communicate.
Xentropy is a TypeScript monorepo split into applications and shared packages, with strict boundaries between them.
Applications
| App | Responsibility |
|---|---|
apps/web | The web console: public and authenticated surfaces, session handling |
apps/api | The service hub: identity, data integrations, charts, artifact services |
apps/worker | Background compute with dedicated chart-worker and artifact-worker entry points |
apps/artifact-mcp | MCP endpoints for external agents and tooling |
Shared packages
| Layer | Packages | Contains |
|---|---|---|
| Contracts | auth-contracts, data-contracts, chart-contracts, artifact-contracts, worker-contracts | Canonical schemas: DataFrame, ChartSpec/Binding, artifact models, the worker job protocol |
| SDKs | artifact-sdk, chart-sdk | Client operations mapped to versioned REST paths |
| Engines | chart-core, motion-core | Validation, compilation, timeline evaluation |
| Renderers | chart-renderer, motion-renderer | Server-side ECharts/Sharp and Remotion/Three.js pipelines |
| UI | @repo/ui, @xentropy/theme | Component primitives and the semantic design tokens |
| Runtime | worker-runtime | Worker pools, leases, health monitors |
@xentropy/* names domain libraries and contracts; @repo/* names shared UI
and configuration.
The five subsystems
- Tabular data — typed DataFrames, owned datasets with versions, and the connection providers behind them.
- Charts — declarative specs, live/snapshot bindings, multi-format exports.
- Motion — scene graphs, timeline evaluation, deterministic rendering.
- Workspace — artifacts, revisions, outputs, shares, and publications.
- Async workers — the job protocol that moves heavy rendering off the request path.
How a request flows
Browser → apps/web (same-origin /api) → apps/api → contracts/engines
↘ async job → workers → outputsDetails: service boundaries and the worker protocol.