cartograph-engine

module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2026 License: Apache-2.0

README

Cartograph

Cartograph

ci Go Reference Go version Licence Release

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

Open http://localhost:8080. cartograph serve -h lists every setting (CARTOGRAPH_ADDR, CARTOGRAPH_VAULT, 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.

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, under ten seconds
just ci       # everything CI runs, in CI's order
just release  # static binaries for linux/amd64 and linux/arm64
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
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
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/merge/       the CRDTs under shared editing
pkg/uiconformance/ the suite every interface passes
examples/minimal a fictional produce cooperative
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

docs/ARCHITECTURE.md for the system in diagrams, the extension points and the clean-architecture mapping; docs/adr/ for the decisions behind it; docs/DEPLOYMENT.md and docs/SERVERLESS.md to run it; docs/EXTENDING.md to add a kind, a store, a codec, an authenticator or a transport; CONTRIBUTING.md for the loop; STYLE.md for code and commits; VERSIONING.md for what a release promises; AGENTS.md for the short brief; SECURITY.md to report a vulnerability; CODE_OF_CONDUCT.md for how we treat each other.

Directories

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/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.
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.
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/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/segment
Package segment validates the slice tree beyond its JSON Schema.
 Package segment validates the slice tree beyond its JSON Schema.
kinds/settings
Package settings implements the Settings kind's one rule beyond its JSON Schema: it is the only singleton kind, so its metadata.id must always be "default".
 Package settings implements the Settings kind's one rule beyond its JSON Schema: it is the only singleton kind, so its metadata.id must always be "default".
kinds/stakeholdermap
Package stakeholdermap implements the StakeholderMap kind's rules beyond its JSON Schema: a map is scoped to a piece of work rather than to any manifest at all, and it scores each resource once.
 Package stakeholdermap implements the StakeholderMap kind's rules beyond its JSON Schema: a map is scoped to a piece of work rather than to any manifest at all, and it scores each resource once.
printer
Package printer is the port through which a rendered document becomes a PDF.
 Package printer is the port through which a rendered document becomes a PDF.
printer/chromium
Package chromium prints HTML to PDF with a headless Chromium.
 Package chromium prints HTML to PDF with a headless Chromium.
render
sentence
Package sentence composes the sentences Cartograph stores in parts.
 Package sentence composes the sentences Cartograph stores in parts.
spa
Package spa embeds the web interface's build and serves it at "/", falling back to index.html for any path that is not a real file, so client-side routes resolve on a hard refresh.
 Package spa embeds the web interface's build and serves it at "/", falling back to index.html for any path that is not a real file, so client-side routes resolve on a hard refresh.
store
Package store defines the two ports the engine is built against (ManifestStore and OperationalStore) and the record shapes they persist.
 Package store defines the two ports the engine is built against (ManifestStore and OperationalStore) and the record shapes they persist.
store/conformance
Package conformance is the one test suite that both the SQLite and the in-memory store adapters must pass, proving they are interchangeable behind the store.ManifestStore and store.OperationalStore ports.
 Package conformance is the one test suite that both the SQLite and the in-memory store adapters must pass, proving they are interchangeable behind the store.ManifestStore and store.OperationalStore ports.
store/manifestmeta
Package manifestmeta reads metadata.name and metadata.labels out of a manifest's text, for the store adapters that index both beside each version.
 Package manifestmeta reads metadata.name and metadata.labels out of a manifest's text, for the store adapters that index both beside each version.
store/memory
Package memory is the in-memory ManifestStore and OperationalStore adapter used by tests and by the conformance suite.
 Package memory is the in-memory ManifestStore and OperationalStore adapter used by tests and by the conformance suite.
store/sqlite
Package sqlite is the SQLite adapter for both store.ManifestStore and store.OperationalStore, backed by modernc.org/sqlite (a pure-Go driver, no cgo).
 Package sqlite is the SQLite adapter for both store.ManifestStore and store.OperationalStore, backed by modernc.org/sqlite (a pure-Go driver, no cgo).
store/vault
Package vault implements store.ManifestStore over a directory tree: files are the source of truth.
 Package vault implements store.ManifestStore over a directory tree: files are the source of truth.
yamlfmt
Package yamlfmt writes YAML the way the vaults are written by hand.
 Package yamlfmt writes YAML the way the vaults are written by hand.
pkg
client
Package client is the port an interface uses to work with Cartograph: the web interface, the terminal interface, a bot, a test.
 Package client is the port an interface uses to work with Cartograph: the web interface, the terminal interface, a bot, a test.
client/inproc
Package inproc is the client.Client over an engine in the same process: no wire, no serialisation beyond the codec.
 Package inproc is the client.Client over an engine in the same process: no wire, no serialisation beyond the codec.
client/remote
Package remote is the client.Client over the HTTP contract: what an interface uses when the engine is another process, on this machine (a UNIX socket) or elsewhere (TCP, through whatever proxy the deployment runs).
 Package remote is the client.Client over the HTTP contract: what an interface uses when the engine is another process, on this machine (a UNIX socket) or elsewhere (TCP, through whatever proxy the deployment runs).
merge
Package merge is the data structure under multiplayer editing: a last-writer-wins map over a manifest's leaf paths, which is a CRDT (Shapiro et al., "A comprehensive study of Convergent and Commutative Replicated Data Types", 2011, section 3.2, LWW-Register and LWW-Map).
 Package merge is the data structure under multiplayer editing: a last-writer-wins map over a manifest's leaf paths, which is a CRDT (Shapiro et al., "A comprehensive study of Convergent and Commutative Replicated Data Types", 2011, section 3.2, LWW-Register and LWW-Map).
uiconformance
Package uiconformance is the one suite every interface to Cartograph must pass: the web interface, the terminal interface, and whatever an organisation builds.
 Package uiconformance is the one suite every interface to Cartograph must pass: the web interface, the terminal interface, and whatever an organisation builds.
uiconformance/clientdriver
Package clientdriver is the reference Driver: it does what a person does, through a client.Client alone, walking the contract's flow.
 Package clientdriver is the reference Driver: it does what a person does, through a client.Client alone, walking the contract's flow.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.