The highest tagged major version is
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
go run ./cmd/cartograph serve ./examples/minimal # copy the example first if you will write
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
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
docs/ SETUP, ARCHITECTURE, DEPLOYMENT, SERVERLESS, EXTENDING, UI_CONTRACT, MULTIPLAYER, DESIGN_RULES, TAXONOMY
justfile every command; flake.nix pins what they run with
Read next
docs/ARCHITECTURE.md for the system in diagrams, the extension
points and the clean-architecture mapping; 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 cartograph/contract/schemas so the compiled binary is self-contained.
|
Package contract embeds the JSON Schema files from cartograph/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. |
|
sentence
Package sentence composes the sentences Cartograph stores in parts.
|
Package sentence composes the sentences Cartograph stores in parts. |
|
spa
Package spa embeds the built SPA (cartograph/web, built with `npm run build` into web/dist and synced here by `make generate`, since Go embed cannot reach outside its module) 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 built SPA (cartograph/web, built with `npm run build` into web/dist and synced here by `make generate`, since Go embed cannot reach outside its module) 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. |
Click to show internal directories.
Click to hide internal directories.