On this page
fact_check
Backend Gap Register
Current backend completion register for platform administrators.
Backend Gap Register
This page summarizes the backend completion state that platform administrators
should track. Sources are adr/0001-remaining-backend-gaps.md,
matrix.md, and the current route contract under backend/docs/.
Contract Status
| Area | Status |
|---|---|
| Cahier route backlog | All expected backend routes are represented in Swagger. |
| Swagger wildcard | Not tracked as a product route; concrete Swagger routes are served. |
| Frontend | Owned separately, with both frontend BFF and dashboard in the repo. |
| Hedera | Real adapter, smart contracts, and deployment/test scripts still deferred. |
| WORM/Object Lock | Deferred by product direction. |
Closed Backend Slices
| Slice | Current behavior |
|---|---|
| Billing operator admin routes | BILLING_OPERATOR can use tenant-selected admin billing dashboard, usage, receipts, report list/download, and export routes with explicit tenant_id. Responses exclude certificate PDFs, canonical proof JSON, and proof payload content. |
| License grant import and quota rules | Imports validate instance_fingerprint, duplicate grant IDs, commercial chain, dates, addendum/revocation references, org-tree allocation limits, and quotas where configured. |
| Notification delivery | SMTP/webhook delivery records status, retries with backoff, updates DLQ metadata, renders branded email templates, and updates billing export delivery metadata. |
| Production observability | API/worker telemetry heartbeats, queue depth/in-flight/DLQ metrics, proof pending/failed gauges, DB connection gauges, signer operation metrics, alert rules, dashboard panels, and runbooks are implemented for the Grafana/Loki/Tempo/Prometheus/OpenTelemetry stack. |
| API contract polish | backend/docs/api-contract-status.md reports no missing cahier backlog endpoints. |
| Agent ingestion hardening | ISO one-time enrollment tokens are validated by prefix/hash, expiry, consumed state, and revocation state. Enrolled-agent API keys are write-only, linked to enrollment state, update last_seen, and persist PKI/mTLS-ready identity metadata. |
| CI/CD and delivery | The Gitea workflow includes migration discipline checks, parallel-safe compose E2E, generated Swagger/HeyAPI freshness, Go tests, security scans, SBOM/provenance, image build/scan/publish, and a dedicated migrator image. |
| Billing/reporting pass | Volume, success-rate, CO2 reporting, restricted SQL billing views, monthly report artifacts, and report/export endpoints are implemented. |
Active Backend Work
No active implementation branch is tracked in this docs site. Operators should still treat the gaps below as open before production acceptance.
Blocked Or Deferred Work
| Area | Blocking input |
|---|---|
| Production agent PKI and enrollment issuer policy | Final trust roots, certificate revocation source, mTLS forwarding contract, ISO token issuer ownership, and production enrollment approval policy. |
| Production signer | Final remote Signer protocol, mTLS material, key IDs, rotation metadata, transaction signing, HMAC, decrypt, PAdES, and TSA behavior. |
| Hedera anchoring | Network, account, contract IDs, mirror-node behavior, finality semantics, explorer URL format, Exaion smart-contract deployment, SDK adapter, key resolver, and replay policy. |
| Storage infrastructure | Final bucket names, versioning policy, write-only billing drop ownership, SSE/KMS settings, and retention schedules. WORM/Object Lock remains deferred. |
| Kubernetes/Harbor deployment | Kubernetes or Helm target and secret ownership. |
Current Implementation Gaps To Track
| Gap | Operational impact |
|---|---|
| Real Hedera anchoring is absent. | Certificates can be issued with CERTIFIED_NO_ANCHOR; public verification cannot prove real on-chain finality until adapter/contracts/config are complete. |
| Ingest listener mTLS enforcement is not final. | Agent enrollment can issue/store PKI-ready identity metadata, but production mTLS termination/forwarding policy must be wired before exposing the standalone gateway to agents. |
| Proof state notifications are incomplete. | Webhook/email delivery exists, but proof.failed, proof.rejected, and proof.awaiting_license producers are not fully connected. |
| S3 write-only billing push and DKIM/PGP delivery policy are incomplete. | Billing exports can be generated and downloaded; hardened external delivery remains infra/product work. |
| License duration types are deferred. | MONTHLY, ANNUAL, MULTI_YEAR, and PERPETUAL semantics are not in the signed grant model yet. |
| Production backup/retention policy is infra-owned. | App retention workers exist, but final storage retention, immutability, and restore process must be validated in the target environment. |
Refresh Checks
Before closing backend work that changes routes, schemas, docs, or generated clients:
cd backend
make swagger
make route-contract
go test ./...
For full-stack backend coverage with the local compose stack:
docker compose up --build -d
cd backend
make e2e