Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cynsta.com/llms.txt

Use this file to discover all available pages before exploring further.

Spendra separates the synchronous gateway path from background processing and finance reporting. This keeps spend enforcement close to the provider request while keeping rollups, alerts, exports, and reconciliation out of the latency-sensitive path.

​
System overview

Client or agent
  -> Spendra gateway
  -> atomic budget reservation
  -> upstream AI provider
  -> settlement and spend event
  -> booked ledger entry
  -> transactional outbox
  -> worker rollups, alerts, exports, and reconciliation

​
Services

​
Web dashboard

The dashboard is a Next.js application used by finance, platform, and operational owners. It reads organization-scoped management data through the API and never accesses service-role credentials directly from the browser.

​
API and gateway

The Fastify service owns both public gateway traffic and authenticated management APIs. Gateway traffic uses Spendra API keys and provider-native request shapes. OpenAI-compatible Responses, Files, and Chat Completions routes proxy to OpenAI. Provider-specific Chat Completions routes proxy to OpenAI, OpenRouter, Google Gemini API, Vertex AI, Azure OpenAI, and Anthropic. Management traffic uses Supabase Auth sessions and application authorization checks.

​
Worker

The worker processes background jobs such as transactional outbox delivery, dashboard rollup refreshes, alert creation, reconciliation, and export generation.

​
Database and Auth

Postgres is the system of record for organizations, hierarchy, policies, reservations, spend events, ledger entries, audit records, and outbox jobs. Supabase Auth provides dashboard identity in the managed V1 topology.

​
Hot path

Every governed provider request follows the same enforcement flow:
  1. Authenticate the Spendra API key.
  2. Resolve actor, organization, hierarchy scopes, provider scopes, and provider-aware model scopes.
  3. Resolve every applicable policy.
  4. Reserve hard-cap budget atomically in Postgres.
  5. Proxy the provider-native request upstream only after reservation succeeds.
  6. Preserve streaming or non-streaming response semantics.
  7. Extract usage, calculate cost, settle the reservation, and write spend and ledger records.
  8. Write audit metadata and outbox events for downstream work.
The hot path does not send emails, run anomaly scans, refresh dashboards, generate CSV exports, or perform webhook delivery.

​
Financial records

Spendra intentionally separates request traces from financial records:
  • Gateway request: the request attempt and policy/provider metadata.
  • Spend event: normalized usage and cost derived from provider traffic.
  • Ledger entry: booked financial record used for finance views, audit, reconciliation, and exports.
Blocked requests create gateway and audit records but do not create spend events or ledger entries.

​
Security boundaries

  • Provider API keys are server-side runtime secrets.
  • Supabase service-role credentials are server-side only.
  • Spendra API key secrets are shown once and stored only as HMAC/hash material.
  • Prompt text, response text, tool arguments, and streamed output chunks are not persisted.
  • Logs must not include bearer tokens, provider keys, prompt bodies, response bodies, or generated output.
  • Production API startup requires Postgres and exact browser CORS origins through SPENDRA_ALLOWED_ORIGINS.
  • Management, gateway, and unauthenticated requests are rate limited before expensive work is performed. /health is public for load balancers; /metrics requires the bearer scrape token and should remain private at ingress.
  • Management responses are capability-scoped. Sensitive provider, notification, domain, membership, and key metadata is redacted unless the user’s role grants the matching capability.