Architecture

henosis is a semantic routing engine. It does not store your operational data. It holds a compiled model of what entities exist, what they look like, and where their data lives — then uses that model to resolve queries against your source systems at call time. It is an intelligence layer that sits above existing systems and makes them coherently queryable by both humans and AI.

Three components

There are three things to know about, and only three:

Component	What it is	Who writes it
Ontology	Your model of the operation, authored in YAML — entities, their bindings to source systems, and how they connect	You
Engine	Compiles that YAML, then resolves every query against your sources at call time and serves the result over REST and MCP	henosis
Canvas	The visual workspace over the engine — maps, trends, entity detail, agent-arrangeable panels	henosis (coming soon)

The ontology is the model, the engine runs it, and the Canvas is where people see it. Everything else — the compiler, the embedded store, the traversal, the API — is engine internals.

1. Ontology — your model, in YAML

You define your world in YAML: a Project manifest declaring named connections, and one EntityType per file. Each EntityType carries its own inline bindings — how identity, spatial, relationships, and state map onto a source table, plus a per-property binding for each observation time-series.

The model is deliberately opinionated rather than a blank graph. Because identity, location, observation, documents, and relationships are first-class roles, the engine knows an observation is a time-series and a location is a place — which is what lets a map, a trend chart, or an agent's tools be driven straight from your model.

Two rules matter here:

• The YAML is the source of truth. Everything downstream is derived from it and never hand-edited. There is no migration system — you change the YAML and recompile.
• A single authoritative source per EntityType section. Sources are never merged field-by-field. A second system describing the same real-world thing becomes its own linked EntityType, or is correlated via external_ids.

See Ontology & data sources for the shape of the YAML itself.

2. Engine — compile, federate, serve

The engine turns that YAML into live answers. It does three jobs.

Compile

henosis compile validates the YAML against generated JSON Schema (errors include the path, the expected shape, and a spec reference) and writes the compiled model into one embedded DuckDB file — conventionally <project>/.henosis/ontology.duckdb, gitignored like any build artifact. There is no external database to run. That file holds three things:

1. Ontology — the compiled EntityType schemas, relationship declarations, named connections (with credential templates left unresolved), the per-type data_source bindings, per-property observation bindings, and derived_from definitions.
2. Graph store — graph_nodes / graph_edges, populated by henosis sync from the relationship bindings and queried via recursive CTEs (or duckpgq for richer patterns).
3. sync_state — per-binding sync watermarks; the one piece of state that isn't a pure function of the YAML.

Compiling fully rebuilds the ontology tables from YAML every run (a drop-and-recreate), leaving sync_state and the graph tables intact.

Federate

At serve time the engine opens ontology.duckdb read-only as its main connection, then ATTACHes every source connection into that same session. This is the key move: DuckDB resolves unqualified table names against the session's default catalog, so ontology lookups (SELECT … FROM entity_types) stay unqualified while source tables are reached as <connection>.<table>. Ontology lookups, graph traversal, and federated source queries are therefore all just SQL against one query planner — there is no dual-backend adapter to maintain, and no copy of your data anywhere.

Serve

henosis serve runs a single HTTP process over one engine and exposes the model two ways, plus a dev UI:

• REST API at /v1 — for applications, systems, and the Canvas.
• MCP tools at /mcp (with --mcp) — the same capabilities as typed tools for AI agents.
• The explorer — a built-in dev UI (Ontology / Sources / Query / Graph) for checking your model as you author it.

An application on REST and an agent on MCP reason over the exact same compiled model.

3. Canvas — coming soon

The Canvas is the human surface over the engine: a visual workspace of maps, trends, entity detail, and panels that an agent can arrange for you in response to a question. It is a client of the same /v1 REST contract anything else would use — it holds no model of its own and no privileged access, which is why a person on the Canvas, an application on REST, and an agent on MCP all see one consistent picture.

Federation, not replacement

henosis never stores entity instances, relationship instances, or observation values. It stores schema and routing only. Your systems of record stay authoritative; henosis resolves against them at call time. There is no ETL, no migration, and no cache of your data to keep fresh.

A corollary the design holds to strictly: no domain knowledge lives in code. There is no if entity_type == "Well" anywhere in the engine, serving layer, or Canvas. Everything domain-specific lives in your YAML — which is why the same engine drives a gas field, a maintenance backlog, or an electricity network without a line of henosis changing.

Where next

• Ontology & data sources — the shape of the YAML: connections, EntityType bindings, observations, derived state, and documents.
• Quickstart — run the compile → sync → serve pipeline against the worked example.