onboarding / project plan

apercue.ca + quicue.ca
the full stack

Two CUE modules. One generic graph engine with 13 W3C specs (apercue). One infrastructure platform with 35 providers and a static API (quicue). This page covers both: architecture, build plan, live demos, and how they fit together.

Start here

What apercue does

apercue is a CUE module that turns typed dependency graphs into W3C-standard linked data. You define resources and their dependencies. CUE computes everything else: topology, critical paths, compliance checks, gap analysis. Every W3C artifact is a different cue export -e expression on the same graph.

Traditional semantic web

Model data in RDF triples. Load into a triplestore. Write SPARQL queries per view. Run a SHACL processor to validate shapes. Serialize to JSON-LD. Five runtime components. Five failure points. Five things to deploy and monitor.

apercue.ca

Define typed resources in CUE. Run cue export -e <projection>. One binary. Zero servers. 13 W3C projections. CUE's constraint lattice does both the querying (replaces SPARQL) and the validation (replaces SHACL) in a single evaluation pass.

Architecture

What's in each directory

vocab/

Core types. #Resource is the base node type. #TypeRegistry manages the type system. context.cue defines the JSON-LD @context with 19 W3C namespace prefixes.

7 files

patterns/

The engine. Graph analysis (topology, depth, critical path, cycle detection) and W3C projections (SHACL, PROV-O, DCAT, ODRL, etc.). Each file is one projection of the same graph.

22 files, 78 definitions

charter/

Constraint-first planning. #Charter declares what "done" looks like with phase gates. #GapAnalysis evaluates a graph against a charter and emits a SHACL sh:ValidationReport.

1 file

views/

Vocabulary projections. #TypeVocabulary emits SKOS ConceptSchemes. #OrgChart emits W3C Org structures. Both project from the type registry, not the graph directly.

2 files

examples/

Four complete, working examples: university course prerequisites (12 courses), beef bourguignon recipe (17 steps), software release tracker (10 tasks), laptop supply chain (14 parts). Each uses the same patterns.

4 examples

self-charter/

The project models itself. 41 deliverables across 8 phases. Uses #GraphLite with precomputed topology (because 41 nodes would timeout the recursive graph engine).

41 nodes, 8 phases

w3c/

Evidence package for W3C Community Group engagement. Generates conformance evidence for all 13 specs. 64 validation tests pass. Export with cue export ./w3c/ -e evidence.<field>.

64 tests passing

site/

Static site deployed to apercue.ca via Cloudflare Pages. HTML + D3 visualizations. Data files in site/data/ are pre-exported from CUE. You're reading this page right now.

8 pages

tools/

Build scripts and validators. toposort.py precomputes topology for large graphs. build-site.sh exports all site data. validate-w3c.py checks JSON-LD output against specs.

11 tools
Build plan

8 phases, 41 deliverables, all satisfied

The project tracks its own build using #Charter and #GapAnalysis. Every phase has a gate. Every gate lists its required deliverables. All 8 gates are satisfied. This timeline shows what was built, in order.

Phase 1 Foundation

Core type system. Every resource gets a name, @type (struct-as-set), and optional depends_on. JSON-LD @context wires up W3C namespace prefixes. Viz contract defines the D3 data shape.

resource-schema type-registry jsonld-context repo-scaffold viz-contract
Phase 2 Engine

The graph engine: #Graph computes topology, depth, ancestors, roots, leaves. Analysis patterns add critical path (CPM), cycle detection, connected components. Validation patterns produce sh:ValidationReport. Charter module adds gap analysis.

graph-engine analysis-patterns validation-patterns lifecycle-patterns charter-module
Phase 3 W3C Projections

Each W3C spec gets a single CUE file that projects the graph into that standard's format. SHACL for validation reports. SKOS for type taxonomies. OWL-Time for scheduling. EARL for test assertions. Same graph, different -e expression.

shacl-projection skos-projection owl-time-projection earl-projection
Phase 4 Domain Examples

Four examples prove domain-agnosticism. Course prerequisites (education), beef bourguignon (cooking), project tracker (PM), laptop assembly (manufacturing). All four use the same patterns. All four produce valid SHACL reports.

example-course-prereqs example-recipe example-project-tracker example-supply-chain
Phase 5 Publish

Documentation, GitHub repo, Cloudflare Pages deployment. The novelty doc explains what's new in three tones (academic, practitioner, executive). Knowledge base tracks architectural decisions (18 ADRs).

docs-readme docs-w3c-index docs-novelty kb-setup github-repo cf-pages
Phase 6 Hardening

SafeID constraints ensure all identifiers are ASCII-safe. CI workflow validates on every push. Specs-registry tracks W3C coverage as a single source of truth. Regen-check catches stale exports.

safeid-constraints ci-workflow specs-registry site-build ci-regen-check
Phase 7 Wire the Stack

apercue becomes a shared library. quicue.ca imports it for infrastructure-specific patterns. Canonical URL context, live charter visualization, homelab mirror, CI auto-deploy.

w3c-namespace-cleanup context-canonical-url charter-status-tracking charter-live-viz quicue-semantic-sync ci-auto-deploy kb-charter-bridge homelab-mirror
Phase 8 Dashboards

Site data locality (pre-exported JSON instead of runtime CUE eval in browser). Homelab site deployment. CPM overlay on charter graph. Projections dashboard showing SHACL + OWL-Time + CPM together.

site-data-locality homelab-site-deploy charter-cpm-overlay projections-dashboard
Language

CUE concepts you need

CUE is a constraint-based configuration language. If you know JSON and a typed language, you can read CUE. These six patterns appear everywhere in apercue.

struct-as-set

Instead of arrays, apercue uses structs with true values for set membership. O(1) lookup, clean merging via unification, no duplicates possible.

"@type": {Database: true, Monitored: true} depends_on: {"design": true, "review": true} // check membership: if resource["@type"]["Database"] != _|_ { ... }

comprehensions

CUE's for loops build structs or lists at eval time. These replace SPARQL queries. They're deterministic and fully resolved before any output.

// all resources of type "Database" databases: { for name, r in graph.resources if r["@type"]["Database"] != _|_ { (name): r } }

_|_ (bottom)

CUE's "undefined" value. field != _|_ means "this field exists." Used for existence checks, optional field detection, and error handling. If two constraints conflict, the result is _|_.

// does this resource have ancestors? if r._ancestors[target] != _|_ { "yes, it's a descendant" }

hidden fields ( _ prefix)

Fields starting with _ are private to the package. They don't appear in cue export output. Use them for intermediate computations. Public fields are the API surface.

_tasks: { ... } // private: input data _charter: charter.#Charter // private: charter config gaps: charter.#GapAnalysis // public: exported result

unification ( & )

CUE merges two values by intersecting their constraints. This is how you apply a pattern to data. If the data doesn't satisfy the pattern, evaluation fails.

// apply the #Graph pattern to your input graph: patterns.#Graph & {Input: _tasks} // apply critical path analysis to the graph cpm: patterns.#CriticalPath & { Graph: graph Weights: {for name, t in _tasks {(name): t.time_days}} }

definitions ( # prefix)

Types (schemas) in CUE are called definitions. #Graph, #Charter, #Resource are definitions. They constrain what fields are allowed and what values they can hold. They're never exported directly.

// in patterns/graph.cue: #Graph: { Input: {[string]: vocab.#Resource} // ... computed fields } // in your code: graph: patterns.#Graph & {Input: _tasks}
Standards

13 W3C specs, one graph

Each spec is a CUE projection. The -e flag selects which one. "Full" means the spec's core terms are emitted and the output parses in rdflib with the expected types; it is not a conformance claim. "Partial" means core terms are covered.

SpecDepthExport expression (from w3c/)
JSON-LD 1.1Fullevidence.context
SHACLFullevidence.shacl
SKOSFullevidence.skos_taxonomy
EARLFullevidence.earl_report
OWL-TimeFullevidence.time_report
PROV-OFullevidence.prov_report
VoIDFullevidence.void_description
DCAT 3Fullevidence.dcat_catalog
DQVFullevidence.quality_report
ODRL 2.2Partialevidence.odrl_policy
Activity StreamsPartialevidence.activity_stream
Web AnnotationPartialevidence.annotation_collection
W3C OrgPartialevidence.org_report
RDFS/OWLPartialevidence.owl_ontology
Dublin CoreVocab(in @context)
schema.orgVocabevidence.schema_graph
VC 2.0Structuralevidence.verifiable_credential
Infrastructure layer

quicue.ca: infrastructure on apercue

quicue.ca imports apercue's generic graph engine and adds infrastructure-specific types, 35 provider templates, and a static API. Same patterns, different domain. The relationship: apercue is the library, quicue.ca is the application.

107pattern definitions
40+resource types
35provider templates
19examples
654pre-computed API responses

Four-layer architecture

Definition
vocab/ + patterns/; Core schemas (#Resource with identity, network, hosting, dependencies) and graph algorithms (#InfraGraph, #ImpactQuery, #BlastRadius, #SinglePointsOfFailure, #DeploymentPlan).
Template
template/*/; 35 provider-specific action registries. Each provider maps resource types to executable commands. Proxmox, Docker, VyOS, Vault, GitLab, Caddy, etc. Commands have {host} and {container_id} placeholders filled at compile time.
Value
examples/*/; 19 concrete infrastructure graphs. The datacenter example has 30 resources with 654 resolved commands. Each example is a complete, working graph with impact queries, SPOF detection, and deployment plans.
Interaction
ou/; Role-scoped views (ops/dev/readonly) with W3C Hydra JSON-LD API. server/ builds a static API: CUE pre-computes all 654 responses, served from Cloudflare Pages. Zero runtime graph traversal.

Key patterns (beyond apercue)

#ImpactQuery

"What breaks if X goes down?" Computes transitive dependents of any resource. Returns the blast radius as a subgraph.

#BlastRadius

Failure propagation analysis. Given a failed node, which layers are affected? How many resources are unreachable?

#SinglePointsOfFailure

Finds resources where failure cascades to multiple dependents. The nodes you need redundancy on.

#DeploymentPlan

Layer-by-layer startup ordering. Which resources can start in parallel at each depth level? Computed from the topology.

#BindCluster

Provider matching by @type overlap. Selects the right command templates for each resource based on its types. No if-then cascades.

#RollbackPlan

If layer N fails during deployment, what's the undo sequence? Reverse of the deployment plan, scoped to affected layers.

Templates

35 provider templates

Each provider has metadata, an action registry (what commands it supports per resource type), and a working example. Provider selection happens by @type set intersection, not configuration switches.

Compute
proxmox govc powercli kubevirt
Container / Orchestration
docker incus k3d kubectl argocd
CI/CD
dagger gitlab woodpecker
Networking
vyos caddy nginx
DNS
cloudflare powerdns technitium
Identity / Secrets
vault keycloak
Monitoring
zabbix grafana
IaC / Automation
terraform opentofu ansible awx
Backup / Storage
restic pbs garage harbor
Database / DCIM / Provisioning
postgresql netbox foreman
Workflow

Commands to start with

Validate

# validate everything (cross-package)
$ cue vet ./... -c

# validate a single example
$ cue vet ./examples/course-prereqs/

Explore

# human-readable summary
$ cue eval ./examples/course-prereqs/ -e summary

# charter gap analysis (is everything done?)
$ cue eval ./examples/course-prereqs/ -e gaps.complete

# critical path summary
$ cue eval ./examples/course-prereqs/ -e cpm.summary

Export W3C JSON-LD

# SHACL validation report
$ cue export ./examples/course-prereqs/ -e gaps.shacl_report --out json

# OWL-Time schedule
$ cue export ./examples/course-prereqs/ -e cpm.time_report --out json

# critical path sequence
$ cue export ./examples/course-prereqs/ -e cpm.critical_sequence --out json

Build site data

# rebuild all site JSON from CUE
$ bash tools/build-site.sh stage _public

# local preview
$ bash tools/deploy-local.sh serve

W3C evidence (all 13 specs)

# export any spec evidence (from project root)
$ cue export ./w3c/ -e evidence.dcat_catalog --out json
$ cue export ./w3c/ -e evidence.shacl --out json
$ cue export ./w3c/ -e evidence.prov_report --out json
Full picture

How it all fits together

apercue is the library. Everything else imports it and adds domain-specific types. The generic graph engine and W3C projections are shared across all downstream modules.

apercue.ca (generic)

Graph engine, W3C projections, charter planning. 78 pattern definitions. 13 W3C specs. Domain-agnostic. import "apercue.ca/patterns@v0"

quicue.ca (infrastructure)

107 pattern definitions. 35 providers. 40+ resource types. Static API with 654 endpoints. Hydra JSON-LD. import "quicue.ca/patterns@v0"

Knowledge graph

quicue-kg

Knowledge graph framework with reasoning and federation patterns on top of apercue.

Housing

cmhc-retrofit

CMHC housing retrofit graphs. Imports apercue for charter-based tracking of retrofit programs.

Additional modules

orche / boot / cab

Multi-site federation, bootstrap sequencing, and Change Advisory Board reporting. All import quicue.ca.