cartograph-engine

module

v2.10.1 Latest Latest Go to latest Published: Oct 9, 2026 License: Apache-2.0

README ¶

Cartograph

A declarative capture engine for what an organisation has decided to do: goals, programmes, projects, operations, KPIs and the data sources behind them, as manifests in a directory, validated against a contract, rendered as documents. One Go binary with its interface embedded. Apache License 2.0.

This repository is the engine: the contract, the Go core, the command line, the public packages other repositories build on. The web and terminal interfaces are in cartograph-ui.

Run it

just serve        # a copy of examples/minimal on 127.0.0.1:8080
just serve laya   # the same, with the Laya decision model (deploy/laya)

Open http://localhost:8080. cartograph serve -h lists every setting (CARTOGRAPH_ADDR, CARTOGRAPH_VAULT, CARTOGRAPH_STORE, CARTOGRAPH_CODEC, CARTOGRAPH_AUTH, ...); docs/DEPLOYMENT.md explains them, the container image and identity.

Or, with nothing checked out: nix run github:ProjectCartograph/cartograph-engine -- serve ./my-vault.

In containers: just image builds the image from the flake, and compose.yaml runs it on one vault volume. compose.ha.yaml (just ha-up) runs the highly available shape on one machine: Postgres, two stateless replicas and a load balancer. On Kubernetes, the Helm chart in deploy/helm/cartograph runs either shape; docs/DEPLOYMENT.md says how to size and operate it.

Build and test it

Nix is the toolchain (docs/SETUP.md: Linux, macOS, Windows through WSL2): install it once and every just recipe enters the flake itself, on x86_64 or aarch64.

just test     # the gate: fake adapters, a few seconds
just ci       # everything CI runs, in CI's order
just release  # static binaries for every platform (docs/CROSS.md)
just image    # the container image, from the flake, loaded into docker

The binary embeds the web interface. Every recipe that compiles fetches the cartograph-ui release named in UI_VERSION first and refuses it unless it matches UI_SHA256; just ui ../cartograph-ui/dist embeds a local interface build instead, and just ui puts the release back.

Layout

contract/        openapi.yaml, one JSON Schema per kind, one flow per stepped kind: the truth
crdt/            the Rust crate behind internal/crdt/automerge/automerge.wasm; just generate rebuilds it
cmd/cartograph/       the binary: serve, ready, validate, import, export, diff, list, snapshot,
                 check, render, handoff, apply, exclude, recover
internal/engine/ the core: validate, commit, version, diff, check, hand off, shared drafts
internal/kinds/  the registry of kinds and each kind's rules
internal/store/  ports and adapters: vault (files), sqlite, memory, postgres
internal/store/postgres/ the stateless store: versions, working copies, bundles, shared drafts
internal/crdt/   the CRDT port and its Automerge adapter (WebAssembly on wazero)
internal/fanout/ hints between replicas: memory, postgres (LISTEN/NOTIFY)
internal/syncserver/ the sync socket: automerge-repo protocol v1 over a WebSocket
internal/codec/  manifest syntax: yaml, json
internal/auth/   identity and policy: none, proxy; allow, roles
internal/printer/ PDF: chromium, none
internal/api/    the HTTP driving adapter; gen/ is generated from the contract
pkg/client/      the port every interface uses, in-process and remote
pkg/uiconformance/ the suite every interface passes
examples/minimal a fictional produce cooperative, imperfect on purpose: its checks show what the engine catches, and fixing them with an agent is the way to learn it (ADR 0019)
deploy/          the Helm chart (helm/cartograph), and the Postgres just helm-kind tests it on (kind/)
compose*.yaml    one replica on a vault; the highly available shape on one machine
internal/spa/    the embedded web interface: a cartograph-ui release, fetched, never committed
docs/            SETUP, ARCHITECTURE, DEPLOYMENT, SERVERLESS, EXTENDING, UI_CONTRACT, MULTIPLAYER, DESIGN_RULES, TAXONOMY
docs/adr/        architecture decision records, one decision per file
UI_VERSION       the cartograph-ui release the binary embeds; UI_SHA256 pins its bytes
justfile         every command; flake.nix pins what they run with

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
cartograph command Command cartograph is the one binary: serve, validate, import, export, diff, list.	Command cartograph is the one binary: serve, validate, import, export, diff, list.
internal
api Package api is the thin driving adapter between the generated strict HTTP server (package apigen) and the engine.	Package api is the thin driving adapter between the generated strict HTTP server (package apigen) and the engine.
api/gen Package apigen provides primitives to interact with the openapi HTTP API.	Package apigen provides primitives to interact with the openapi HTTP API.
auth Package auth is the identity port: who is making this request, and may they do what they are asking.	Package auth is the identity port: who is making this request, and may they do what they are asking.
auth/access Package access is the Authorizer for an access list (docs/adr/0011, TAXONOMY.md D27): four roles, each a bundle of permissions, and teams that scope a contributor's work.	Package access is the Authorizer for an access list (docs/adr/0011, TAXONOMY.md D27): four roles, each a bundle of permissions, and teams that scope a contributor's work.
auth/proxy Package proxy is the Authenticator for a deployment behind an authenticating reverse proxy (oauth2-proxy, Pomerium, Authelia, an ingress with OIDC): the proxy verifies the person and forwards their identity in a header, and this adapter trusts that header.	Package proxy is the Authenticator for a deployment behind an authenticating reverse proxy (oauth2-proxy, Pomerium, Authelia, an ingress with OIDC): the proxy verifies the person and forwards their identity in a header, and this adapter trusts that header.
auth/roles Package roles is a role-based Authorizer: principals in a write role may read and write, principals in a read role may read, everyone else is refused.	Package roles is a role-based Authorizer: principals in a write role may read and write, principals in a read role may read, everyone else is refused.
codec Package codec is the port between a manifest's text and its document.	Package codec is the port between a manifest's text and its document.
codec/conformance Package conformance is the suite every codec.Codec adapter must pass: what the engine relies on, written once, run against each syntax.	Package conformance is the suite every codec.Codec adapter must pass: what the engine relies on, written once, run against each syntax.
codec/json Package json is the JSON codec.	Package json is the JSON codec.
codec/yaml Package yaml is the YAML codec: yaml.v3 to read, yamlfmt to write, so a file saved by Cartograph keeps the two-space indentation the vaults are written in by hand.	Package yaml is the YAML codec: yaml.v3 to read, yamlfmt to write, so a file saved by Cartograph keeps the two-space indentation the vaults are written in by hand.
config Package config is the one place the process reads its environment.	Package config is the one place the process reads its environment.
contract Package contract embeds the JSON Schema files from contract/schemas so the compiled binary is self-contained.	Package contract embeds the JSON Schema files from contract/schemas so the compiled binary is self-contained.
crdt Package crdt is the port between the engine and the replicated data type under every shared draft.	Package crdt is the port between the engine and the replicated data type under every shared draft.
crdt/automerge Package automerge is the crdt port's adapter: Automerge, compiled to WebAssembly from the crate in crdt/ and run on wazero, so the engine stays pure Go (CGO_ENABLED=0) and speaks the same document format and sync protocol as every interface using the stock Automerge libraries (docs/adr/0007).	Package automerge is the crdt port's adapter: Automerge, compiled to WebAssembly from the crate in crdt/ and run on wazero, so the engine stays pure Go (CGO_ENABLED=0) and speaks the same document format and sync protocol as every interface using the stock Automerge libraries (docs/adr/0007).
crdt/conformance Package conformance is the suite every adapter of the crdt port must pass.	Package conformance is the suite every adapter of the crdt port must pass.
decide Package decide is the port through which the engine asks typed questions of a piece of text: which of these options it is, or whether a statement holds of it, each answer a calibrated probability (docs/adr/0023).	Package decide is the port through which the engine asks typed questions of a piece of text: which of these options it is, or whether a statement holds of it, each answer a calibrated probability (docs/adr/0023).
decide/conformance Package conformance is what every decide.Decider must do: answer every question asked, pick a Choice from its own options with probabilities that are probabilities, give a YesNo a probability, and stop when its context is cancelled.	Package conformance is what every decide.Decider must do: answer every question asked, pick a Choice from its own options with probabilities that are probabilities, give a YesNo a probability, and stop when its context is cancelled.
decide/fake Package fake is a decide.Decider for the gate's tests: it answers each question as a test scripts it, by the question's name, and any question not scripted as a model unsure of it would (every option alike, a yes or no at one half).	Package fake is a decide.Decider for the gate's tests: it answers each question as a test scripts it, by the question's name, and any question not scripted as a model unsure of it would (every option alike, a yes or no at one half).
decide/laya Package laya is a Decider backed by Laya, an open decision model, run as a sidecar beside Cartograph (deploy/laya): the model needs a runtime the static binary does not carry, so it is reached over HTTP on the same host or network.	Package laya is a Decider backed by Laya, an open decision model, run as a sidecar beside Cartograph (deploy/laya): the model needs a runtime the static binary does not carry, so it is reached over HTTP on the same host or network.
document Package document reads a document's text: its sections, by their headings, and the registers its tables hold.	Package document reads a document's text: its sections, by their headings, and the registers its tables hold.
engine Package engine is the kind-agnostic manifest engine: it validates manifests against their schema, references and kind rules, stores immutable versions, computes diffs, and indexes cross-manifest references.	Package engine is the kind-agnostic manifest engine: it validates manifests against their schema, references and kind rules, stores immutable versions, computes diffs, and indexes cross-manifest references.
evaluate Package evaluate judges a change agents use the way docs/EVALUATING.md says: by criteria scored from the server and the trace, never from an agent's report, run after run on one frozen build, until enough pass in a row.	Package evaluate judges a change agents use the way docs/EVALUATING.md says: by criteria scored from the server and the trace, never from an agent's report, run after run on one frozen build, until enough pass in a row.
fanout Package fanout is the port that carries a small message from one replica of the engine to every other (docs/adr/0008).	Package fanout is the port that carries a small message from one replica of the engine to every other (docs/adr/0008).
fanout/conformance Package conformance is the suite every fanout.Bus adapter must pass.	Package conformance is the suite every fanout.Bus adapter must pass.
fanout/memory Package memory is the in-process fanout.Bus: every Bus made from one Hub delivers to every subscriber of that Hub.	Package memory is the in-process fanout.Bus: every Bus made from one Hub delivers to every subscriber of that Hub.
fanout/postgres Package postgres is the fanout.Bus over Postgres LISTEN/NOTIFY, so a deployment whose state is in Postgres needs no second service for fan-out (docs/adr/0008).	Package postgres is the fanout.Bus over Postgres LISTEN/NOTIFY, so a deployment whose state is in Postgres needs no second service for fan-out (docs/adr/0008).
identity Package identity is who a request runs as and what they ask to do, without HTTP: the part of the identity port (docs/ARCHITECTURE.md) the engine may know.	Package identity is who a request runs as and what they ask to do, without HTTP: the part of the identity port (docs/ARCHITECTURE.md) the engine may know.
kinds Package kinds is the registry of every manifest kind: its schema file and its rules function, if it has one beyond schema and generic reference validation.	Package kinds is the registry of every manifest kind: its schema file and its rules function, if it has one beyond schema and generic reference validation.
kinds/goal Package goal implements the Goal kind's rules beyond its JSON Schema: parent presence by level (a goal has no parent; an objective requires a goal as parent; an outcome requires an objective goal as parent), unique key result ids within the goal, the key result unit-by-kind rule, and the objective must-be-qualitative rule.	Package goal implements the Goal kind's rules beyond its JSON Schema: parent presence by level (a goal has no parent; an objective requires a goal as parent; an outcome requires an objective goal as parent), unique key result ids within the goal, the key result unit-by-kind rule, and the objective must-be-qualitative rule.
kinds/kit Package kit holds the small, dependency-free types that both the engine and the per-kind rule packages need.	Package kit holds the small, dependency-free types that both the engine and the per-kind rule packages need.
kinds/kpireadings Package kpireadings validates a KPI's series beyond its JSON Schema.	Package kpireadings validates a KPI's series beyond its JSON Schema.
kinds/operation Package operation implements the Operation kind's rules beyond its JSON Schema: a service's recurring funding lines (TAXONOMY.md D39) and its mandate's issuer (D43).	Package operation implements the Operation kind's rules beyond its JSON Schema: a service's recurring funding lines (TAXONOMY.md D39) and its mandate's issuer (D43).
kinds/portfolio Package portfolio implements the Portfolio kind's rules beyond its JSON Schema (TAXONOMY.md D32).	Package portfolio implements the Portfolio kind's rules beyond its JSON Schema (TAXONOMY.md D32).
kinds/portfoliodecisions Package portfoliodecisions implements the PortfolioDecisions kind's rules beyond its JSON Schema (TAXONOMY.md D32).	Package portfoliodecisions implements the PortfolioDecisions kind's rules beyond its JSON Schema (TAXONOMY.md D32).
kinds/programme Package programme implements the Programme kind's rules beyond its JSON Schema: the risk list a project and a programme share, checked here without phases, because a programme holds no timeline, and the gap citations they also share.	Package programme implements the Programme kind's rules beyond its JSON Schema: the risk list a project and a programme share, checked here without phases, because a programme holds no timeline, and the gap citations they also share.
kinds/project Package project implements the Project kind's rules beyond its JSON Schema: unique key result ids within each objective, the key result unit-by-kind rule, the objective must-be-qualitative rule, unique deliverable ids, unique success criteria ids, a success criterion's derivedFrom must name exactly one key result or deliverable that actually exists in this project, at most one funding line per currency, and a risk's escalate.reason is required when escalate.flag is true; every local reference resolves to an item this project actually has; and a dependency edge belongs to the dependency type and lands by a phase the timeline actually has.	Package project implements the Project kind's rules beyond its JSON Schema: unique key result ids within each objective, the key result unit-by-kind rule, the objective must-be-qualitative rule, unique deliverable ids, unique success criteria ids, a success criterion's derivedFrom must name exactly one key result or deliverable that actually exists in this project, at most one funding line per currency, and a risk's escalate.reason is required when escalate.flag is true; every local reference resolves to an item this project actually has; and a dependency edge belongs to the dependency type and lands by a phase the timeline actually has.
kinds/purpose Package purpose implements the Purpose kind's one rule beyond its JSON Schema: a workspace states one purpose, so its metadata.id is always "default".	Package purpose implements the Purpose kind's one rule beyond its JSON Schema: a workspace states one purpose, so its metadata.id is always "default".