README
¶
RankeDB
Everything is Knowledge — Knowledge is Everything.
A provenance-first foundation for knowledge systems.
Please visit github.com/flocko-motion/ranke-graph to learn about the underlying concepts - this repo focusses on the implementation.
RankeDB is the server: a hexagonal wrapper around the
ranke-go library, which owns the graph
model and verification. One process serves exactly one Ranke-Archive, assembled from
exactly one configuration supplied at launch.
Repository structure
| Path | What |
|---|---|
openapi/ |
The REST API spec — the single source of truth — and the artifacts generated from it |
cmd/ranke-db/ |
The server binary: run <config>, verify <config> |
cmd/generator/ |
A contributing client that seeds a running instance over the REST API |
internal/core/ |
The core: endpoints, access, persistence composition, contribution |
config/ |
Configuration — the composition root |
adapters/ |
One directory per adapter port: storage, sequencer, signer, vault, auth, endpoints |
examples/ |
Launchable example configurations |
docs/, openspec/ |
Documentation and capability specs |
frontend/ |
Ranke Explorer — the browser client (see frontend/README.md) |
Building
make # regenerate from the OpenAPI spec, then build, vet, test and lint
make build # compile bin/ranke-db and bin/generator
make smoke # launch the minimal example, seed it over the API, read it back, shut down
Running
An instance is one binary and one config file — there is no runtime reconfiguration. The admin cycle is edit → run → observe → stop.
ranke-db verify examples/minimal/config.json # offline, secret-free check of the config
ranke-db run examples/minimal/config.json # resolve secrets, assemble the stack, serve
For a dev server with something in it, make dev SEED=example launches the minimal
example with a throwaway signing key and seeds it as soon as it answers. SEED=release
writes a release process — four signing identities, two packages travelling from a git
snapshot to a signed-off release, and the CVEs their scans mention — and SEED=chain
grows a larger archive one contribution at a time. Seeding is a client — a
contributor is an application-held key, so bin/generator signs its own claims and
sends them to POST /contribute.
See examples/minimal/ for the smallest launchable stack.
API
openapi/openapi.yaml is the single source of truth for the REST API. make generate
produces the Go server interface, the TS client and the HTML + Markdown references from
it; the references are browsable under docs/openapi/.
Papers
The theory lives in the separate ranke-graph
repository as Typst (.typ) sources — not in this repo. Read the .typ source directly,
or run make docs to pull copies into docs/papers/:
01-ranke-graph/ranke-graph.typ— foundational model and design philosophy. Required reading.02-ranke-db/ranke-db.typ— the RankeDB architecture paper. Read it before implementation work.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
adapters
|
|
|
auth
package: auth / authn type: interface + factory + dispatcher job: the Auth port — a credential in, a Principal out — plus factory and dispatcher limits: identity only; authority is access's, checking the backends' (-> internal/core/access)
|
package: auth / authn type: interface + factory + dispatcher job: the Auth port — a credential in, a Principal out — plus factory and dispatcher limits: identity only; authority is access's, checking the backends' (-> internal/core/access) |
|
auth/apikey
package: apikey / authn type: adapter job: authenticate a request by matching its API key against configured account keys limits: recognises keys, never mints them; holds digests only (-> auth.New, internal/core/access)
|
package: apikey / authn type: adapter job: authenticate a request by matching its API key against configured account keys limits: recognises keys, never mints them; holds digests only (-> auth.New, internal/core/access) |
|
auth/noauth
package: noauth / authn type: adapter job: authenticate every request as one fixed subject — the no-auth backend limits: no credential checking; for single-tenant/dev stacks (-> auth.New)
|
package: noauth / authn type: adapter job: authenticate every request as one fixed subject — the no-auth backend limits: no credential checking; for single-tenant/dev stacks (-> auth.New) |
|
endpoints
package: endpoints / transport type: interface + factory job: the Endpoint port — bind a transport to core.Handle — plus the factory limits: contract + dispatch; transports live in sub-packages (-> adapters/endpoints/rest_http, mcp_http)
|
package: endpoints / transport type: interface + factory job: the Endpoint port — bind a transport to core.Handle — plus the factory limits: contract + dispatch; transports live in sub-packages (-> adapters/endpoints/rest_http, mcp_http) |
|
endpoints/mcp_http
package: mcp_http / transport type: adapter job: MCP/HTTP endpoint backend (agent tools) — implements the endpoints.Endpoints port limits: stub; implementation lands when the endpoint port is built (-> adapters/endpoints)
|
package: mcp_http / transport type: adapter job: MCP/HTTP endpoint backend (agent tools) — implements the endpoints.Endpoints port limits: stub; implementation lands when the endpoint port is built (-> adapters/endpoints) |
|
endpoints/rest_http
package: rest_http / transport type: logic job: extract the request's auth credential from the wire and carry it to the handlers limits: extraction only; core resolves it and applies grants (-> internal/core)
|
package: rest_http / transport type: logic job: extract the request's auth credential from the wire and carry it to the handlers limits: extraction only; core resolves it and applies grants (-> internal/core) |
|
sequencer
package: sequencer / coordination type: adapter job: a steerable clock for --dev — real time until told otherwise limits: time source only; who may steer it is core's access decision (-> core)
|
package: sequencer / coordination type: adapter job: a steerable clock for --dev — real time until told otherwise limits: time source only; who may steer it is core's access decision (-> core) |
|
signer
package: signer / crypto type: interface + factory job: the Signer port — the server's signing identity — plus its factory limits: contract + dispatch; keys live in the backends (-> inmemory, openbao, azure)
|
package: signer / crypto type: interface + factory job: the Signer port — the server's signing identity — plus its factory limits: contract + dispatch; keys live in the backends (-> inmemory, openbao, azure) |
|
signer/inmemory
package: inmemory / crypto type: adapter job: load a config-provided ed25519 private key into a signer.Signer the server signs merges with limits: never generates a key; the key is supplied by config (inline, env(), or vault()) -> signer.New
|
package: inmemory / crypto type: adapter job: load a config-provided ed25519 private key into a signer.Signer the server signs merges with limits: never generates a key; the key is supplied by config (inline, env(), or vault()) -> signer.New |
|
signer/inmemory/inmemorytest
package: inmemorytest / crypto type: test-support job: the inmemory signer's conformance setup hook and key fixtures, beside the backend limits: a test helper; only the conformance driver imports it (-> adapters/signer)
|
package: inmemorytest / crypto type: test-support job: the inmemory signer's conformance setup hook and key fixtures, beside the backend limits: a test helper; only the conformance driver imports it (-> adapters/signer) |
|
signer/openbao
package: openbao / crypto type: adapter job: sign via an OpenBao Transit key that never leaves the server limits: ed25519 Transit keys, which stay in OpenBao (-> adapters/signer)
|
package: openbao / crypto type: adapter job: sign via an OpenBao Transit key that never leaves the server limits: ed25519 Transit keys, which stay in OpenBao (-> adapters/signer) |
|
signer/openbao/openbaotest
package: openbaotest / crypto type: test-support job: the OpenBao Transit signer's conformance setup hook — a real OpenBao via podman, transit enabled limits: a test helper; it skips when podman is absent (-> adapters/signer conformance, tools/podman)
|
package: openbaotest / crypto type: test-support job: the OpenBao Transit signer's conformance setup hook — a real OpenBao via podman, transit enabled limits: a test helper; it skips when podman is absent (-> adapters/signer conformance, tools/podman) |
|
storage
package: storage / composition type: factory job: build one ranke.Universe from a storage section — a leaf, or a composite limits: wiring only; the persistence logic is ranke-go's adapters (-> github.com/flocko-motion/ranke-go)
|
package: storage / composition type: factory job: build one ranke.Universe from a storage section — a leaf, or a composite limits: wiring only; the persistence logic is ranke-go's adapters (-> github.com/flocko-motion/ranke-go) |
|
vault
package: vault / secrets type: interface + factory job: the Vault port — a secret reference in, its value out — plus its factory limits: contract + dispatch; secret fetching lives in the backends (-> adapters/vault/openbao, azure)
|
package: vault / secrets type: interface + factory job: the Vault port — a secret reference in, its value out — plus its factory limits: contract + dispatch; secret fetching lives in the backends (-> adapters/vault/openbao, azure) |
|
vault/azure
package: azure / secrets type: adapter job: resolve vault(ref) secrets from Azure Key Vault limits: SCAFFOLD — construction only, no fetching yet (-> adapters/vault)
|
package: azure / secrets type: adapter job: resolve vault(ref) secrets from Azure Key Vault limits: SCAFFOLD — construction only, no fetching yet (-> adapters/vault) |
|
vault/openbao
package: openbao / secrets type: adapter job: resolve vault(ref) secrets from an OpenBao KV v2 engine limits: KV v2 reads only; the mount + credentials come from the vault section (-> adapters/vault)
|
package: openbao / secrets type: adapter job: resolve vault(ref) secrets from an OpenBao KV v2 engine limits: KV v2 reads only; the mount + credentials come from the vault section (-> adapters/vault) |
|
cmd
|
|
|
generator
command
package: main / cmd type: logic job: the REST client the generator contributes through limits: transport only; the graph it carries is the grower's (-> graph.go)
|
package: main / cmd type: logic job: the REST client the generator contributes through limits: transport only; the graph it carries is the grower's (-> graph.go) |
|
ranke-db
command
package: main / cmd type: entrypoint job: the ranke-db binary — a cobra CLI handing a config to the config package limits: CLI wiring only; decrypt/parse/resolve/assemble live in config (-> config)
|
package: main / cmd type: entrypoint job: the ranke-db binary — a cobra CLI handing a config to the config package limits: CLI wiring only; decrypt/parse/resolve/assemble live in config (-> config) |
|
package: config / composition type: struct job: decrypt/parse the launch config and either check it (Verify) or assemble the adapter stack (Run) limits: the only component that sees the whole config; adapters get scope.Section slices (-> Verify, Run)
|
package: config / composition type: struct job: decrypt/parse the launch config and either check it (Verify) or assemble the adapter stack (Run) limits: the only component that sees the whole config; adapters get scope.Section slices (-> Verify, Run) |
|
scope
package: scope / config type: struct job: a resolution-free Section over a flat map, for known values and tests limits: flat leaves only; cfgSection resolves env()/vault() (-> config)
|
package: scope / config type: struct job: a resolution-free Section over a flat map, for known values and tests limits: flat leaves only; cfgSection resolves env()/vault() (-> config) |
|
package: frontend / static asset type: embed shim job: the default (non-embedding) build of Explorer limits: the `!explorer` counterpart to embed.go's build tag
|
package: frontend / static asset type: embed shim job: the default (non-embedding) build of Explorer limits: the `!explorer` counterpart to embed.go's build tag |
|
go
module
|
|
|
internal
|
|
|
core
package: core / orchestration type: orchestrator job: run a Request through the pipeline — authenticate, authorize, execute — driving the ports limits: the composition of the ports, assembled by config (-> config, adapters/*)
|
package: core / orchestration type: orchestrator job: run a Request through the pipeline — authenticate, authorize, execute — driving the ports limits: the composition of the ports, assembled by config (-> config, adapters/*) |
|
core/access
package: access / policy type: checker job: decide whether a system account may exercise a CRUD right on a branch limits: pure policy from config; no ports, no ctx; core loops it for delete (-> config, core)
|
package: access / policy type: checker job: decide whether a system account may exercise a CRUD right on a branch limits: pure policy from config; no ports, no ctx; core loops it for delete (-> config, core) |
|
Package openapi provides primitives to interact with the openapi HTTP API.
|
Package openapi provides primitives to interact with the openapi HTTP API. |
|
tools
|
|
|
podman
package: podman / tools type: test-support job: run a throwaway container for an adapter's real-counterpart test, on a free port, torn down after limits: a test helper; it skips without podman and waits for the port, not for readiness
|
package: podman / tools type: test-support job: run a throwaway container for an adapter's real-counterpart test, on a free port, torn down after limits: a test helper; it skips without podman and waits for the port, not for readiness |
Click to show internal directories.
Click to hide internal directories.