# mizcausevic-dev/kinetic-gain-visualizer architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/kinetic-gain-visualizer, 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-visualizer
- Repository: https://github.com/mizcausevic-dev/kinetic-gain-visualizer

## Overview

The Kinetic Gain Protocol Suite Visualizer is a browser-based React app for inspecting JSON documents from eleven protocol specs, with additional architecture, tool-catalog, and audit-chain views. The main workflow starts when a user opens the app and pastes or edits a document: the app detects its spec from a top-level version field, selects a spec-aware renderer, and displays the result; unrecognized documents fall back to raw JSON. The README documents deep links for the main views and an example gallery.

#### Components

##### Browser app and document visualization
- **Browser bootstrap** — `src/main.tsx`: mounts the React app into the page’s `root` element and loads the app stylesheet.
- **Visualizer and view coordinator** — `src/App.tsx`: maintains the app’s view and document interaction, calls spec detection, and dispatches recognized documents to their renderer or unknown documents to raw JSON.
- **Spec detection contract** — `src/detect.ts`: identifies document types using the version-field contract documented in the README; the app imports `detectSpec`, `SPECS`, and `specInfo` from this module.
- **Examples gallery data** — `src/examples.ts`: supplies the examples used by the app; `App` imports `EXAMPLES` and `AEO_EXAMPLE`.
- **Spec-aware document renderers** — `src/renderers/AeoRenderer.tsx`: anchors the renderer subsystem; `App` imports separate renderers for the supported specs, while the README documents eleven spec-specific renderers plus a raw-JSON fallback. These render documents for display rather than validating them against external schemas.
- **Shared renderer presentation primitives** — `src/renderers/common.tsx`: shared card, field, and pill components are imported by sampled renderers, including the decision-card, classroom-AUP, and clinical-AI renderers.

##### Protocol reference views
- **Protocol and tool catalog data** — `src/protocol-data.ts`: provides protocol and tool metadata, including tool descriptions and inputs; its file comments say this catalog mirrors data from the MCP server repository.
- **Interactive tools catalog** — `src/views/Tools.tsx`: filters and displays tools using protocol and tool data imported from the catalog.
- **Protocol architecture view** — `src/views/Architecture.tsx`: presents protocol metadata and describes the external `mcp-kinetic-gain` server; it imports protocol definitions and counts from the catalog.

##### Browser-side audit demonstration
- **Audit-chain implementation** — `src/lib/audit-chain.ts`: builds a sample governance-event chain and verifies event IDs, hashes, and chain links using browser cryptographic APIs; its comments describe it as a browser-side mirror of another project’s verification logic.
- **Audit stream view** — `src/views/AuditStream.tsx`: builds and verifies sample chains, displays verification results, and supports a tampering demonstration and JSON download.

#### Relationships

- **App user** -> **Browser bootstrap**: opens the browser app; the repository documents the app’s deployed URL and local development entry.
- **Browser bootstrap** -> **Visualizer and view coordinator**: mounts the React `App` component.
- **App user** -> **Visualizer and view coordinator**: supplies or edits a document in the visualizer; the README describes pasting documents and the editor/gallery workflow.
- **Visualizer and view coordinator** -> **Spec detection contract**: calls detection and spec-info functions for the parsed document; the app excerpt shows these imports and the detection call.
- **Visualizer and view coordinator** -> **Examples gallery data**: reads examples for the gallery; the app excerpt shows the imports and example-loading function.
- **Visualizer and view coordinator** -> **Spec-aware document renderers**: renders the selected spec-specific renderer or raw JSON fallback; the app excerpt shows the dispatch branches.
- **Spec-aware document renderers** -> **Shared renderer presentation primitives**: sampled renderers import shared card, field, and pill components.
- **Visualizer and view coordinator** -> **Interactive tools catalog**: renders this view when the selected view is `tools`.
- **Interactive tools catalog** -> **Protocol and tool catalog data**: reads protocol and tool definitions for filtering and display.
- **Visualizer and view coordinator** -> **Protocol architecture view**: renders this view when the selected view is `architecture`.
- **Protocol architecture view** -> **Protocol and tool catalog data**: reads protocol definitions and tool counts.
- **Visualizer and view coordinator** -> **Audit stream view**: renders this view when the selected view is `audit-stream`.
- **Audit stream view** -> **Audit-chain implementation**: calls the chain builder and verifier on initial load, reset, and tampered-chain actions.
- **Browser cryptographic APIs** -> **Audit-chain implementation**: supplies the Web Crypto SHA-256 operation used for canonical hashes; this is a browser API, not a repository component.

#### Coverage limits

The source excerpts are partial. They do not show the full app’s JSON parsing and input-error handling, the complete detection table, or every renderer’s fields. The audit view demonstrates a locally generated sample chain; the sampled code does not establish a connection to a live audit service or to the external MCP server.

Main entry points: [`src/App.tsx`](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/App.tsx) (Visualizer), [`src/main.tsx`](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/main.tsx) (Browser bootstrap), [`src/renderers/AeoRenderer.tsx`](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/renderers/AeoRenderer.tsx) (Document renderers), [`src/views/Tools.tsx`](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/Tools.tsx) (Tools catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_browser_bootstrap["Browser bootstrap<br/>React entry point"]
  node_visualizer["Visualizer<br/>View coordinator"]
  node_spec_detection["Spec detection<br/>Detection contract"]
  node_examples["Examples gallery<br/>Example data"]
  node_renderers["Document renderers<br/>Spec-aware rendering"]
  node_renderer_primitives["Renderer primitives<br/>Shared presentation"]
end

subgraph group_reference["Protocol reference views"]
  node_protocol_data["Protocol and tool data<br/>Catalog data"]
  node_tools_view["Tools catalog<br/>Interactive view"]
  node_architecture_view["Architecture view<br/>Protocol reference view"]
end

subgraph group_audit["Audit demonstration"]
  node_audit_view["Audit stream<br/>Audit demonstration view"]
  node_audit_chain["Audit-chain logic<br/>Chain builder and verifier"]
end

node_app_user["App user<br/>External actor"]
node_web_crypto["Browser cryptographic APIs<br/>External browser API"]

node_app_user -->|"opens"| node_browser_bootstrap
node_browser_bootstrap -->|"mounts"| node_visualizer
node_app_user -->|"edits document"| node_visualizer
node_visualizer -->|"detects spec"| node_spec_detection
node_visualizer -->|"reads examples"| node_examples
node_visualizer -->|"renders document"| node_renderers
node_renderers -->|"uses"| node_renderer_primitives
node_visualizer -->|"renders view"| node_tools_view
node_tools_view -->|"reads catalog"| node_protocol_data
node_visualizer -->|"renders view"| node_architecture_view
node_architecture_view -->|"reads definitions"| node_protocol_data
node_visualizer -->|"renders view"| node_audit_view
node_audit_view -->|"builds and verifies"| node_audit_chain
node_web_crypto -->|"hashes events"| node_audit_chain

click node_browser_bootstrap "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/main.tsx"
click node_visualizer "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/App.tsx"
click node_spec_detection "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/detect.ts"
click node_examples "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/examples.ts"
click node_renderers "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/renderers/AeoRenderer.tsx"
click node_renderer_primitives "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/renderers/common.tsx"
click node_protocol_data "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/protocol-data.ts"
click node_tools_view "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/Tools.tsx"
click node_architecture_view "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/Architecture.tsx"
click node_audit_view "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/AuditStream.tsx"
click node_audit_chain "https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/lib/audit-chain.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_browser_bootstrap,node_visualizer,node_spec_detection,node_examples,node_renderers,node_renderer_primitives,node_app_user,node_web_crypto toneBlue
class node_protocol_data,node_tools_view,node_architecture_view toneAmber
class node_audit_view,node_audit_chain toneMint
```

## Components

### Browser app

- [Browser bootstrap](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/main.tsx): React entry point · `src/main.tsx`
- [Visualizer](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/App.tsx): View coordinator · `src/App.tsx`
- [Spec detection](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/detect.ts): Detection contract · `src/detect.ts`
- [Examples gallery](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/examples.ts): Example data · `src/examples.ts`
- [Document renderers](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/renderers/AeoRenderer.tsx): Spec-aware rendering · `src/renderers/AeoRenderer.tsx`
- [Renderer primitives](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/renderers/common.tsx): Shared presentation · `src/renderers/common.tsx`

### Protocol reference views

- [Protocol and tool data](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/protocol-data.ts): Catalog data · `src/protocol-data.ts`
- [Tools catalog](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/Tools.tsx): Interactive view · `src/views/Tools.tsx`
- [Architecture view](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/Architecture.tsx): Protocol reference view · `src/views/Architecture.tsx`

### Audit demonstration

- [Audit stream](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/views/AuditStream.tsx): Audit demonstration view · `src/views/AuditStream.tsx`
- [Audit-chain logic](https://github.com/mizcausevic-dev/kinetic-gain-visualizer/blob/main/src/lib/audit-chain.ts): Chain builder and verifier · `src/lib/audit-chain.ts`

### Other components

- **App user**: External actor
- **Browser cryptographic APIs**: External browser API

## Connections

- App user → Browser bootstrap: opens
- Browser bootstrap → Visualizer: mounts
- App user → Visualizer: edits document
- Visualizer → Spec detection: detects spec
- Visualizer → Examples gallery: reads examples
- Visualizer → Document renderers: renders document
- Document renderers → Renderer primitives: uses
- Visualizer → Tools catalog: renders view
- Tools catalog → Protocol and tool data: reads catalog
- Visualizer → Architecture view: renders view
- Architecture view → Protocol and tool data: reads definitions
- Visualizer → Audit stream: renders view
- Audit stream → Audit-chain logic: builds and verifies
- Browser cryptographic APIs → Audit-chain logic: hashes events