Architecture Reference

Date: 2026-05-10
Status: Current

Responsibility boundaries

edgesentry-rs   Domain-agnostic Rust library + eds CLI.
                ZKP primitives (eds-zkp), audit chain, evaluate, profile engine.
                No business logic. Consumed by clarus via Cargo path deps.

clarus          Data acquisition, storage, and verification layer.
  edge/         Edge daemon — sensor ingestion → evaluate → sign → WORM upload + ZKP proof generation.
  analytics/    Cloudflare Pages — operations monitor, audit chain viewer, B2B verify API.

clarus owns all data generated by the edge (WORM chain, R2 buckets). The B2B /api/verify endpoint is the integration surface for third parties — cost is borne by clarus (CF Workers invocation). documaris reads from clarus browser-side (zero server cost) for its operator UI.

Delivery surfaces

Surface	URL	Runtime
Analytics web app	clarus.edgesentry.io	Browser (Cloudflare Pages)
B2B verify API	`clarus.edgesentry.io/api/verify`	Cloudflare Pages Functions
API documentation	`clarus.edgesentry.io/api-docs`	Cloudflare Pages (Scalar)
Desktop demo app	Local only	Tauri (native binary)

ZKP layer

Proof generation (edge daemon)

When the loaded profile has a registered ZkProgram, the edge daemon generates a zero-knowledge proof for each RiskEvent before uploading the WORM record. The proof commits only the public attestation — raw sensor values never leave the edge device.

Profile	ZkProgram	Private inputs	Public attestation
`sg-bca-greenmark`	`GreenMarkProgram`	EUI, COP, LPD readings	`cert_level`, `all_criteria_pass`, `cop_pass`, `lpd_pass`
`sg-ot-cybersecurity`	`OtIntegrityProgram`	Component hashes, allowlist	`all_authorized`, `unauthorized_count`, `status`

Current framework: Mock (BLAKE3 of public_values). SP1/RISC Zero guest programs are the upgrade path — the proof envelope format (ZkProof) and public API are already final.

The ZkProgram trait and ZkProof type are defined in edgesentry-rs/crates/eds-zkp. Domain-specific implementations live in clarus/edge/src/zkp/.

After each proof cycle the edge writes zkp-latest/{site_id}.json to the raw bucket — a strongly-consistent pointer that allows consumers to find the newest attested record without listing the full chain.

Type contract

schemas/zk-bca-greenmark.json is the canonical JSON Schema for ZkProof and GreenMarkAttestation. Both clarus CI and documaris CI validate against it to prevent silent type divergence.

Proof verification (analytics API)

GET /api/verify?site=<site_id>      Layer 1 — human / machine readable
GET /api/verify/raw?site=<site_id>  Layer 2 — raw proof envelope for B2B integration

See clarus.edgesentry.io/api-docs for the interactive spec, or api-reference.md for a quick reference.

Mock framework: proof_bytes == BLAKE3(public_values_bytes) — verified server-side in the Pages Function via @noble/hashes/blake3.

4-quadrant test matrix:

Site	Scenario	`valid`	`proof_verified`
MCH-OUTLET-042	Q1 — Gold, honest report	`true`	`true`
BLD-HIGHUSE-FAIL	Q2 — Not Certified, honest report	`true`	`true`
BLD-TAMPER-PASS	Q3 — Claims GoldPlus, tampered proof	`false`	`false`
BLD-TAMPER-FAIL	Q4 — Claims Not Certified, tampered proof	`false`	`false`

Web app (Cloudflare Pages)

Pages

Path	Entry point	Purpose
`/`	`index.html`	Analytics — vessel scores
`/live`	`live.html`	Operations Monitor — live heartbeats
`/audit`	`audit.html`	Audit chain verification
`/api-docs`	`api-docs.html`	OpenAPI documentation (Scalar)
`/api/verify`	`functions/api/verify.ts`	B2B verify endpoint
`/api/verify/raw`	`functions/api/verify-raw.ts`	B2B raw proof endpoint
`/api/audit-summary`	`functions/api/audit-summary.js`	Run summary
`/api/audit-index`	`functions/api/audit-index.js`	Key listing

Data flow (browser)

R2 bucket
   └─ Cloudflare Pages Function  (auth proxy — no credentials in browser)
         └─ fetch() in browser
               └─ DuckDB WASM  (SQL over Parquet in-browser, zero server cost)
                     └─ Observable Plot  (charts)

Data flow (B2B API)

Third party  →  GET /api/verify?site=xxx
                     ↓
               Pages Function (verify.ts)
                 1. Read zkp-latest/{site}.json from CLARUS_DEV_PUBLIC_RAW
                 2. Fetch audit record from CLARUS_DEV_PUBLIC_AUDIT
                 3. Decode public_values (base64 JSON)
                 4. Verify: BLAKE3(public_values_bytes) == proof_bytes
                     ↓
               { valid, cert_level, proof_verified, verify_url, ... }

R2 data storage

Three public Cloudflare R2 buckets:

Bucket	Binding	Written by	Read by
`clarus-dev-public-raw`	`CLARUS_DEV_PUBLIC_RAW`	Edge daemon	`/live`, `/api/verify`
`clarus-dev-public-analytics`	`CLARUS_DEV_PUBLIC_ANALYTICS`	edgesentry-rs pipelines	`/` Analytics
`clarus-dev-public-audit`	`CLARUS_DEV_PUBLIC_AUDIT`	Edge daemon	`/audit`, `/api/verify`, `/api/verify/raw`

Object Lock (Standard mode) is enabled on the audit bucket — records are immutable.

Key formats:

Key	Content
`chains/{site_id}/{run_id}/{seq:020}.json`	AuditRecord with optional `zk_proof`
`zkp-latest/{site_id}.json`	Pointer: `{ run_id, last_seq, site_id }`
`live/{site_id}/heartbeats/{ts}.parquet`	Heartbeat snapshots
`live/{site_id}/audit_chain/{ts}.parquet`	Alert summaries

edgesentry-rs

Clarus's Tauri backend and edge daemon both link edgesentry-rs crates via Cargo path dependencies. Both repos must be siblings on disk:

edgesentry/
  edgesentry-rs/   ← Rust engine + eds CLI
  clarus/          ← this repo

documaris

documaris is the operator-facing compliance document platform. It reads attested data from clarus browser-side (DuckDB WASM, zero server cost) and generates compliance documents that embed verify_url for independent verification.

Tauri desktop app

The ui/ directory is a Tauri 2 application — not deployed to the web. Used for the local 14-stage demo. Links edgesentry-rs crates directly via Cargo path dependencies.

Build

analytics/
  vite.config.ts     multi-page Vite build (includes api-docs.html)
  wrangler.toml      R2 bindings + Pages project name
  functions/         Pages Functions (verify.ts, verify-raw.ts, audit-*.js, data proxy)
  schemas/           JSON Schema type contracts
  public/            Static assets (openapi.json)
  dist/              build output → deployed to Cloudflare Pages

Local dev: cd analytics && npm run dev