Architecture Overview

SemanticFed is a managed, multi-tenant cloud service. Your clients — the web app, CLI, MCP server, SDKs, browser extension, VS Code extension, or your own code — call one authenticated GraphQL API. Every request is authenticated and permission-checked before it reaches your data, and the service holds only the control plane: your connectors, models, saved queries, policies, and run history. Your data itself stays in your own systems and is queried in place.

┌───────────────────────────────────────────────────────────┐
│  SemanticFed clients                                       │
│  Web app · CLI · MCP server · Node/Python SDKs · GraphQL   │
│  Browser Extension · VS Code Extension · Custom code       │
└─────────────────────────────┬─────────────────────────────┘
                              │ authenticated GraphQL request
                              ▼
              ┌───────────────────────────────┐
              │  SemanticFed service           │
              │  authentication · permissions  │
              │  sources · model · queries     │
              │  policy · audit · lineage      │
              └───────────────┬───────────────┘
                              │ federated execution (roadmap engine)
                              ▼
        Your registered data sources (queried in place):
        PostgreSQL · MySQL · MongoDB · Snowflake · BigQuery ·
        Redshift · Databricks · ClickHouse · S3/Parquet ·
        REST/GraphQL APIs

Functional areas

The API is organized into three areas:

• sources — connectors, data sources, and connection health probes
• model — semantic models, entities, dimensions, metrics, and relationships
• queries — saved queries, query runs, and access policies

Ecosystem clients

All clients authenticate through the same GraphQL gateways and share the same identity layer:

Client	Transport	Auth	Environment var
Web app	Browser / HTTPS	OAuth2 PKCE	VITE_WSPACE_GATEWAY_URL, VITE_GLOBAL_GATEWAY_URL
CLI	HTTPS	OAuth2 device code	BURDENOFF_ENV
Node SDK	HTTPS	Multiple	Endpoint constructor args
Python SDK	HTTPS	Multiple	Endpoint constructor args
Browser Extension	HTTPS	OAuth2 device code	BURDENOFF_ENV (build time)
VS Code Extension	HTTPS	OAuth2 device code	BURDENOFF_ENV (runtime)
MCP Server	HTTPS / stdio	OAuth2 device code	SEMANTICFED_* env vars
Doctor E2E	HTTPS	Bearer JWT	SEMANTICFED_TARGET

All clients default to production. Switch to local or alpha via BURDENOFF_ENV or explicit endpoint overrides. See Environment Selection.

What the service stores

SemanticFed stores your model and governance metadata, not your data: connector and source definitions (endpoints plus credential references), semantic models, saved queries, access policies, and run records (status, plan summary, sources touched, rows, duration, cache status). Result caching is opt-in and configurable per query.

Design principles

• Query in place, don't copy — the default is zero-copy federation with push-down; copies are an opt-in optimization
• Model once, govern at the edge — one typed semantic layer and one policy model, enforced across every source and tenant
• Authenticated and permission-checked at the boundary — identity is verified and every operation is authorized before any work is done
• Tenant isolation by construction — every query and mutation is workspace-scoped, so cross-tenant access is impossible by design
• No infrastructure for you to run — identity, files, tags, billing, conversations, notifications, and audit are all part of the service

Roadmap

Federated execution against registered sources is performed by the query engine. The run, plan-summary, and cache records are modeled today; the live engine ships on the roadmap.