Skip to content
Velocity

Velocity

Velocity

Schema is the contract. Apply a SchemaDefinition CRD to your Kubernetes cluster. Velocity provisions a Postgres table, REST API, validation, role-based access, search, audit, time-machine history, and observability — automatically, without per-schema code.

The 30-Second Pitch

Velocity is a schema-driven backend platform built in Rust that lives inside Kubernetes. Write a single CRD that describes your data shape, access rules, and retention policy. The platform does the rest: generates the table DDL, enforces field-level RLS, provisions full-text search, records every change in an append-only audit log, keeps 90 days of history hot, archives to S3 Parquet beyond that, and exports metrics to Prometheus.

Three decisions unlock this:

  1. The schema is the source of truth. No separate OpenAPI spec, no migration scripts, no RBAC matrix living in a spreadsheet. One CRD spec drives DDL, validation, search indexing, audit policies, and API route generation.
  2. The API server reads the schema via a Kubernetes informer per replica, not RPC from the operator. This keeps the data plane fast and decoupled from the control plane.
  3. The database role is non-superuser, NOBYPASSRLS from day one. Row-level security is not theater — it is a real backstop enforced by the database itself.

Features

CRUD + DSL Query

Generic handlers for any schema. List with filtering, pagination, and sorting. No per-schema route boilerplate.

Full-Text Search

Tier 1: trigram (fast, 90 days hot). Tier 2: Postgres FTS. Tier 3: Typesense (real-time, CDN-aware, typo-tolerant).

Time Machine

Every change recorded. Point-in-time query, diff, restore. 90 days hot in Postgres; warm tier in S3 Parquet up to 5 years.

Append-Only Audit

Hash-linked audit chain. Tamper detection via audit verify command. Immutable proof of who changed what when.

Role-Based Access

7 layers of access control: RBAC, ABAC (CEL), row filters, field filters, masking, Postgres RLS, and validating webhook.

Archive & Purge

Automatic tiering: hot → warm → cold → delete. S3 Parquet warm storage. Lifecycle-driven purges with optional approval gates.

Observability

Structured JSON logging. Prometheus metrics. OpenTelemetry traces. Grafana dashboards auto-generated per schema.

Operational Tooling

velocity CLI for schema management, audit verification, drift detection, and record operations. SLO sweeper for SLA compliance.

Start Here

  • Getting Started — Install, apply your first SchemaDefinition, CRUD a record, verify with the CLI.
  • Installation — Prerequisites, Helm install, RBAC, the critical non-superuser role setup.
  • Hardening — Production checklist: role verification, CEL bounded execution, validating webhook, outbox semantics.
  • Features — Deep dives: SchemaDefinition, AuthStrategy, Time Machine, Archive, Audit, Search, Observability.
  • API Reference — Every REST route with examples.
  • CLI Reference — Every command from velocity status to velocity archive restore.

Architecture at a Glance

Developer (kubectl apply / velocity CLI)
  ↓
ValidatingWebhook (sanity checks)
  ↓
kube-apiserver (CRDs: SchemaDefinition, AuthStrategy, ArchivePolicy, PurgeRequest, …)
  ↓
velocity-operator (kube-rs; provisions Postgres DDL, HPA, Grafana dashboards, SLO rules)
  ↓
velocity-api (Axum; informer-fed SchemaRegistry; generic CRUD + search + audit + time-machine)
  ↓
Postgres (hot tier + history tables + RLS + audit chain)
  ↓ (Tier-3 search)
Typesense (via CDC outbox)
  ↓ (time-machine 90+ days)
S3 Parquet (warm tier; warm-reader queryable via DataFusion)

What Ships Today (Phase 9)

All core features:

  • CRUD, DSL query, soft delete, optimistic locking, idempotency
  • Authentication: JWT, OIDC, API key, Composite
  • RBAC Layers 1–7: route-level, ABAC, row filter, field filter, masking, Postgres RLS
  • Time Machine: history, point-in-time query, diff, restore (hot 90 days; warm tier up to 5 years)
  • Search: Tiers 1–3 (trigram, FTS, Typesense)
  • Archive: Batch export to S3 Parquet, lifecycle-driven purges
  • Audit: Append-only chain, hash linkage, tamper verification
  • Observability: JSON logging, Prometheus metrics, OTel traces, auto-generated dashboards
  • CLI: Full Phase 9 surface (context, version, status, reconcile, audit, drift, apply, get, describe, delete, diff, record ops, history, restore, grant, revoke, api-key, archive, approve, health, metrics, slo)

Deferred (Phases 10+)

  • Admin Portal (React UI)
  • VersionOperator (CRD versioning via finalizer)
  • OIDC device flow
  • Typed Arrow columns
  • Cron-precise scheduling
  • S3 orphan sweep
  • Sharded archive workers

Key Guarantees

  • Atomicity: Writes to table + history + outbox in one transaction. Either all succeed or none.
  • Consistency: RLS enforced per-row. CEL validation sandboxed (10ms timeout). Breaking schema changes blocked unless explicitly approved.
  • Durability: Postgres WAL archived to S3 every 5 minutes. CNPG provides point-in-time recovery.
  • Isolation: Non-superuser velocity_api role. Session context set per request. Actor ID in logs.
  • Auditability: Every mutation recorded with actor, timestamp, old vs new values, and reason (if required). Chain is hash-linked; tampering detected.

Ready? Head to Getting Started.