# mizcausevic-dev/kinetic-gain-embedded architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/kinetic-gain-embedded, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/kinetic-gain-embedded
- Repository: https://github.com/mizcausevic-dev/kinetic-gain-embedded

## Overview

#### Purpose and principal workflow

`kinetic-gain-embedded` is a TypeScript SDK for SaaS applications that need to enforce buyer-defined data-handling rules and emit verifiable audit events around customer-data use. The main workflow is initiated by an **embedding SaaS application** when its code is about to pass customer data to an AI tool: it loads the buyer’s Decision Card, applies its vault rules to the payload, and emits an event recording the applicable redactions. The SDK provides primitives for producing, storing, and verifying the audit trail; the embedder supplies the application workflow and chooses the event sink.

#### Components

##### SDK entry and policy loading
- **Public SDK surface** — `src/index.ts`: Exports the supported runtime functions, types, and sink implementations to package consumers.
- **Decision Card loader and validator** — `src/decision-card.ts`: Parses and structurally checks buyer-provided cards, or fetches a card from a URL using `fetch`.

##### Data protection and audit events
- **Vault contract enforcement** — `src/vault.ts`: Deep-clones payloads and applies the card’s field rules—tokenize, mask, hash, or drop—returning both transformed data and a redaction list; also supports an injected tokenizer.
- **Audit stream and chain verification** — `src/audit-stream.ts`: Builds events with timestamps, IDs, card reference, and prior-event hash; computes each event hash, optionally signs it, writes it to the configured sink, and exposes chain verification.

##### Cryptographic and event primitives
- **Canonical serialization and hashing** — `src/canonical.ts`: Implements sorted-key canonical JSON, SHA-256 hashing, and the genesis prior-hash constant used by event creation and verification.
- **Ed25519 signing and verification** — `src/sign.ts`: Creates signers from PEM private keys and verifies event signatures against PEM public keys.
- **Time-ordered event IDs** — `src/uuid.ts`: Generates UUID v7 values, used by default for audit event IDs.

##### Event destinations
- **Reference audit sinks** — `src/sinks.ts`: Implements in-memory, NDJSON-file, HTTP POST, and tee sinks; production consumers can provide their own sink through the same write/optional-flush contract.

##### External participants
- **Embedding SaaS application** — `null`: The consumer application initiates policy loading, data protection, and event emission around its customer-data workflow.
- **Buyer / Decision Card issuer** — `null`: Supplies the card that states the authorization and vault rules the SDK applies.
- **Auditor or downstream verifier** — `null`: Replays exported events and can check the hash chain and, when it has the public key, event signatures.

#### Relationships

- **Embedding SaaS application -> Public SDK surface**: Imports the SDK’s exported runtime API; the package entry point re-exports the implementation.
- **Buyer / Decision Card issuer -> Embedding SaaS application**: Supplies the buyer-issued Decision Card used by the embedding application.
- **Embedding SaaS application -> Decision Card loader and validator**: Calls parse on supplied card data or fetches a card from its URL.
- **Decision Card loader and validator -> Embedding SaaS application**: Returns a structurally checked card; the loader does not enforce the card’s full JSON Schema.
- **Embedding SaaS application -> Vault contract enforcement**: Passes a payload and card or contract for field-level transformation before the AI tool receives the payload.
- **Vault contract enforcement -> Embedding SaaS application**: Returns the transformed payload and redaction list for the caller to use and record.
- **Embedding SaaS application -> Audit stream and chain verification**: Calls `emit` with event details, including redactions when applicable.
- **Audit stream and chain verification -> Time-ordered event IDs**: Uses UUID v7 as the default event-ID generator.
- **Audit stream and chain verification -> Canonical serialization and hashing**: Hashes canonical event bodies and invokes the same chain logic when verifying events.
- **Audit stream and chain verification -> Ed25519 signing and verification**: Calls the configured signer to sign the canonical event body when signing is enabled.
- **Audit stream and chain verification -> Reference audit sinks**: Writes each completed event to the configured sink; the sink may instead be consumer-provided.
- **Reference audit sinks -> Auditor or downstream verifier**: Can deliver events via HTTP or persist them in a file for later replay; actual downstream delivery depends on the selected sink and consumer setup.
- **Auditor or downstream verifier -> Public SDK surface**: A consumer can call the exported chain verifier and signature verifier when replaying events.

#### Coverage limits

Source excerpts establish the core SDK calls and data flow, but do not show the embedder’s application code, its chosen sink configuration, or how a buyer distributes cards and signing keys. The README documents additional use cases and production sink options; those deployment-specific integrations are not established as repository implementations.

Main entry points: [`src/audit-stream.ts`](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/audit-stream.ts) (Audit stream), [`src/decision-card.ts`](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/decision-card.ts) (Decision Card loader), [`src/vault.ts`](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/vault.ts) (Vault enforcement), [`src/sinks.ts`](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/sinks.ts) (Reference audit sinks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External participants"]
  node_embedding_app(("Embedding SaaS app<br/>External application"))
  node_card_issuer(("Decision Card issuer<br/>External actor"))
  node_auditor(("Auditor or verifier<br/>External actor"))
end

subgraph group_sdk_policy["SDK and policy"]
  node_public_sdk["Public SDK surface<br/>SDK entry point"]
  node_card_loader["Decision Card loader<br/>Policy loader"]
end

subgraph group_runtime["Protection and audit"]
  node_vault["Vault enforcement<br/>Data protection"]
  node_audit_stream["Audit stream<br/>Event creation and verification"]
end

subgraph group_audit_infrastructure["Audit infrastructure"]
  node_canonical["Canonical hashing<br/>Serialization and hashing"]
  node_signing["Ed25519 signing<br/>Signing and verification"]
  node_event_ids["Time-ordered IDs<br/>UUID v7 generator"]
  node_audit_sinks["Reference audit sinks<br/>Event destinations"]
end

node_embedding_app -->|"imports"| node_public_sdk
node_card_issuer -->|"supplies card"| node_embedding_app
node_embedding_app -->|"parses or fetches"| node_card_loader
node_card_loader -->|"returns checked card"| node_embedding_app
node_embedding_app -->|"protects payload"| node_vault
node_vault -->|"returns data and redactions"| node_embedding_app
node_embedding_app -->|"emits event"| node_audit_stream
node_audit_stream -->|"generates IDs"| node_event_ids
node_audit_stream -->|"hashes and verifies"| node_canonical
node_audit_stream -.->|"signs events"| node_signing
node_audit_stream -->|"writes event"| node_audit_sinks
node_audit_sinks -.->|"delivers events"| node_auditor
node_auditor -->|"verifies replay"| node_public_sdk

click node_public_sdk "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/index.ts"
click node_card_loader "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/decision-card.ts"
click node_vault "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/vault.ts"
click node_audit_stream "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/audit-stream.ts"
click node_canonical "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/canonical.ts"
click node_signing "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/sign.ts"
click node_event_ids "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/uuid.ts"
click node_audit_sinks "https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/sinks.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_embedding_app,node_card_issuer,node_auditor toneBlue
class node_public_sdk,node_card_loader toneAmber
class node_vault,node_audit_stream toneMint
class node_canonical,node_signing,node_event_ids,node_audit_sinks toneRose
```

## Components

### External participants

- **Embedding SaaS app**: External application
- **Decision Card issuer**: External actor
- **Auditor or verifier**: External actor

### SDK and policy

- [Public SDK surface](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/index.ts): SDK entry point · `src/index.ts`
- [Decision Card loader](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/decision-card.ts): Policy loader · Checks structure; does not enforce the full JSON Schema. · `src/decision-card.ts`

### Protection and audit

- [Vault enforcement](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/vault.ts): Data protection · `src/vault.ts`
- [Audit stream](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/audit-stream.ts): Event creation and verification · `src/audit-stream.ts`

### Audit infrastructure

- [Canonical hashing](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/canonical.ts): Serialization and hashing · `src/canonical.ts`
- [Ed25519 signing](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/sign.ts): Signing and verification · `src/sign.ts`
- [Time-ordered IDs](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/uuid.ts): UUID v7 generator · `src/uuid.ts`
- [Reference audit sinks](https://github.com/mizcausevic-dev/kinetic-gain-embedded/blob/main/src/sinks.ts): Event destinations · Includes in-memory, NDJSON-file, HTTP POST, and tee sinks. · `src/sinks.ts`

## Connections

- Embedding SaaS app → Public SDK surface: imports
- Decision Card issuer → Embedding SaaS app: supplies card
- Embedding SaaS app → Decision Card loader: parses or fetches
- Decision Card loader → Embedding SaaS app: returns checked card
- Embedding SaaS app → Vault enforcement: protects payload
- Vault enforcement → Embedding SaaS app: returns data and redactions
- Embedding SaaS app → Audit stream: emits event
- Audit stream → Time-ordered IDs: generates IDs
- Audit stream → Canonical hashing: hashes and verifies
- Audit stream → Ed25519 signing: signs events · Used when signing is enabled.
- Audit stream → Reference audit sinks: writes event
- Reference audit sinks → Auditor or verifier: delivers events · Downstream delivery depends on the selected sink and consumer setup.
- Auditor or verifier → Public SDK surface: verifies replay