Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fluxamerica.io/llms.txt

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

The platform emits two distinct audit streams, each with its own canonical JSON Schema draft-2020-12 document. SDKs that consume events (via SubscribeAuditTail on the wire, or by reading archived events from cold storage) should validate against the schemas before deserialising — that is the contract.

​
The two streams

StreamSchemaPurposeHash-chained
Per-tenantaudit-event.schema.jsonEvery state-changing operation a tenant performs lands here. The full record CRUD lifecycle, model + field publishes, attachment lifecycle, subscription lifecycle, validator/visibility/computed events.Yes — ADR-0007 hash chain; prev_hash + hash per event, monotonic chain_index per tenant.
Systemsystem-audit-event.schema.jsonLifecycle events that span or precede tenants: provisioning, offboarding, schema fanout, backup take/promote/prune/restore, auth-handshake failures.No (v1) — chain extension is an open design question.
Per-tenant events are scoped to one tenant. System events are observable across the deployment (only the operator’s roles can subscribe). Both streams emit the same envelope-with-discriminator shape: an event_type string selects which payload subschema applies, via oneOf. The full enumerated list of event-type variants — including the rendered description for every variant — is the canonical JSON Schemas themselves. The schemas are the contract.

​
Envelope shape

Both schemas share an envelope-then-payload pattern:
  • A small fixed set of always-required fields at the top level (event_type, occurred_at, plus per-stream specifics).
  • A payload field whose JSON shape depends on event_type, resolved via the oneOf block at the bottom of each schema.

​
Per-tenant envelope

{
  "id":          <ULID>,
  "tenant_id":   <ULID>,
  "occurred_at": <RFC 3339 timestamp>,
  "actor":       { "user_id", "email", "name?" },
  "event_type":  <discriminator>,
  "payload":     <shape selected by event_type>,
  "prev_hash":   <hex sha256 of previous event in this tenant's chain>,
  "hash":        <hex sha256 of this event's canonical bytes>
}
Optional envelope fields the schema permits: correlation_id, causation_id, chain_index. See the canonical schema for the precise required-set + format constraints.

​
System envelope

{
  "event_type":  <discriminator>,
  "occurred_at": <RFC 3339 timestamp>,
  "payload":     <shape selected by event_type>,
  "tenant_id?":  <ULID, when the event names a tenant>
}
System events do not carry actor / id / prev_hash / hash because the stream is not hash-chained in v1.

​
Validating events

Both schemas are pure JSON Schema draft-2020-12. Validate with any conforming library:
  • Python — jsonschema with Draft202012Validator.
  • JavaScript / TypeScript — ajv with the 2020 draft option.
  • Go — santhosh-tekuri/jsonschema v5.
  • Rust — jsonschema crate.
The canonical $id URLs in each schema are stable; cache by URL. The platform does not currently serve the schemas over HTTP; pin them in your SDK or fetch from the repository tag matching your protocol version.

​
Compatibility commitments

The schemas are additive only within a major protocol version:
  • New event_type variants land at the end of each stream’s enum (and at the end of the oneOf). An SDK that does not understand an unknown event_type should log + skip — not error — to remain compatible with forward-rolling deployments.
  • New payload fields land as optional (additive) properties on existing payload shapes. Required-set additions are wire-breaking and require a major version bump.
  • The envelope’s required-set is locked for the lifetime of a major version.
  • Field renames are wire-breaking. The platform never renames a field in-place; it adds a new field and deprecates the old via the ADR-0023 § 8.3 deprecation window.

​
Verifying chain integrity

Per-tenant stream events carry a hash chain (ADR-0007). An SDK that re-verifies chains downstream of a SubscribeAuditTail subscription should walk prev_hash ↔ hash per event in chain-index order; mismatches indicate tampering or schema drift. The canonical hashing function and chain_index ordering rules are documented in the per-tenant schema’s top-level description.

​
Fetching the canonical schemas

The schemas live in the platform repository (fluxamerica/platform). The simplest way for an SDK build to keep them current is to pin them to a release tag and fetch via raw URL — substitute <tag> for the release tag your integration is built against: 
https://raw.githubusercontent.com/fluxamerica/platform/<tag>/docs/audit-event.schema.json
https://raw.githubusercontent.com/fluxamerica/platform/<tag>/docs/system-audit-event.schema.json
Inlining the schemas into this site (which can run hundreds of lines per stream) is deliberately deferred — a future external-generate emitter, tracked as PLAT-190, will surface them directly here as a generated page; until then, pin the file in your build.