# mizcausevic-dev/kg-governance-dashboard architecture

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

## Overview

#### Purpose and principal workflow

This is a browser-only governance dashboard for procurement reviewers, CISOs, and district CIOs. A reviewer opens the deployed SPA; it either loads recent events and follows the live event stream from the upstream audit-stream service, or—when no service URL is configured—shows a synthetic demo stream. The reviewer can inspect trends, producers, and filtered audit events, configure browser-side alerts, and explicitly request an audit-chain verification.

#### Components

##### Application and event input
- **Reviewer** — *(external; null repository path)* Procurement reviewer, CISO, or district CIO who opens the dashboard and uses its views and controls.
- **Audit-stream service** — *(external; null repository path)* Upstream `audit-stream-py` service documented as the source of the event history, SSE stream, and on-demand chain verification.
- **React bootstrap** — `src/main.tsx` Mounts the React application into the page’s root element.
- **Dashboard orchestrator** — `src/App.tsx` Owns the selected tab, event list, connection state, and vendor filter; chooses live or demo input and passes events to dashboard UI.
- **Live audit client** — `src/lib/audit-stream.ts` Reads the runtime URL and implements history and verification REST calls plus an `EventSource` subscription to the stream.
- **Demo event generator** — `src/lib/demo-events.ts` Builds synthetic event history and emits subsequent events when live mode is unavailable.
- **Runtime endpoint configuration** — `public/config.js` Supplies the audit-stream URL at runtime so a deployed dashboard can be repointed without rebuilding.

##### Governance views and interpretation
- **Dashboard shell and status** — `src/components/AppHeader.tsx` Provides header-level dashboard controls and status presentation; the README also documents sidebar, banner, system-log, and status-bar shell elements.
- **Trend overview** — `src/components/OverviewTab.tsx` Derives KPI, hourly, and event-kind summaries from the event list and renders charts; event severity comes from the RMF catalog.
- **Producer activity** — `src/components/ProducersTab.tsx` Groups events by the producer catalog and shows per-kind counts and each producer’s latest event.
- **Audit trail and vendor filtering** — `src/components/AuditTrailTab.tsx` Presents the event trail; the README documents filtering it by vendor mentions in event payloads.
- **Chain verification view** — `src/components/VerifyTab.tsx` Provides the user-facing verification action and result display; the README documents the on-demand chain check.
- **Event and producer contract** — `src/lib/types.ts` Defines the shared governance-event and producer types used by the dashboard.
- **RMF event catalog** — `src/lib/rmf-citations.ts` Maps event kinds to descriptions, severity, and NIST AI RMF citations used in event interpretation.

##### Alerts and derived data
- **Alert rules and browser persistence** — `src/lib/alert-rules.ts` Evaluates match and rolling-threshold rules and reads/writes rules and hits in browser `localStorage`; it also requests permission for and fires desktop notifications.
- **Alert controls and notifications** — `src/components/NotificationBell.tsx` Evaluates incoming events against rules, persists hits, and exposes the bell, hit list, and rule editor to the user.
- **Chart derivations** — `src/lib/chart-utils.ts` Supplies event-stream aggregations for trend and distribution charts.

#### Relationships

- **Reviewer -> React bootstrap:** opens the deployed dashboard; the page’s root element is mounted by the React entry point.
- **React bootstrap -> Dashboard orchestrator:** renders the root application component.
- **Dashboard orchestrator -> Runtime endpoint configuration:** reads the configured stream URL through the live client’s runtime-config lookup.
- **Dashboard orchestrator -> Live audit client:** when configured, requests history and subscribes to the event stream; also closes the subscription on cleanup.
- **Audit-stream service -> Live audit client:** serves history and verification responses and sends stream events; this is an external interface documented by the README and implemented as REST/SSE calls by the client.
- **Dashboard orchestrator -> Demo event generator:** when no live URL is configured, seeds history and starts a synthetic event subscription instead of using the live stream.
- **Dashboard orchestrator -> Dashboard shell and status:** supplies connection state, event count, active tab, and event data to the shell.
- **Dashboard orchestrator -> Trend overview:** passes the current event list for KPI and chart derivation.
- **Dashboard orchestrator -> Producer activity:** passes the current event list for producer-level aggregation.
- **Dashboard orchestrator -> Audit trail and vendor filtering:** passes events and the vendor-filter state.
- **Reviewer -> Chain verification view:** selects the verification view and initiates the on-demand check.
- **Chain verification view -> Live audit client:** requests chain verification; the client makes the verification GET request to the audit-stream service.
- **Dashboard orchestrator -> Alert controls and notifications:** supplies the current event list for alert evaluation.
- **Alert controls and notifications -> Alert rules and browser persistence:** loads and saves rules and hits, evaluates rules, and delegates desktop notification permission and delivery.
- **Trend overview -> RMF event catalog:** looks up severity while computing event-severity KPIs.
- **Producer activity -> RMF event catalog:** looks up event severity for producer event-kind chart colors.
- **Trend overview -> Chart derivations:** obtains hourly and event-kind aggregates for its charts.

#### Coverage limits

The source excerpts are bounded: several UI modules and the chart utility implementation were not sampled. Their responsibilities and some behavior are documented in the README, but internal call details beyond the cited evidence are not established here.

Main entry points: [`src/App.tsx`](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/App.tsx) (Dashboard orchestrator), [`src/components/OverviewTab.tsx`](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/OverviewTab.tsx) (Trend overview), [`src/lib/audit-stream.ts`](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/audit-stream.ts) (Live audit client), [`src/main.tsx`](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/main.tsx) (React bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application and Event Input"]
  node_react_bootstrap["React bootstrap<br/>frontend entry point"]
  node_dashboard["Dashboard orchestrator<br/>frontend application"]
  node_live_client["Live audit client<br/>client library"]
  node_demo_generator["Demo event generator<br/>client library"]
  node_runtime_config["Runtime endpoint configuration<br/>[config.js]"]
end

subgraph group_governance["Governance Views"]
  node_dashboard_shell["Dashboard shell and status<br/>UI component"]
  node_trend_overview["Trend overview<br/>UI component"]
  node_producer_activity["Producer activity<br/>UI component"]
  node_audit_trail["Audit trail and vendor filtering<br/>UI component"]
  node_verify_view["Chain verification view<br/>UI component"]
end

subgraph group_interpretation["Event Interpretation"]
  node_rmf_catalog["RMF event catalog<br/>[rmf-citations.ts]"]
  node_chart_derivations["Chart derivations<br/>[chart-utils.ts]"]
end

subgraph group_alerts["Alerts"]
  node_alert_controls["Alert controls and notifications<br/>UI component"]
  node_alert_rules["Alert rules and browser persistence<br/>rules and persistence"]
end

node_reviewer(("Reviewer<br/>external actor"))
node_audit_service["Audit-stream service<br/>external service"]

node_reviewer -->|"opens dashboard"| node_react_bootstrap
node_react_bootstrap -->|"renders"| node_dashboard
node_dashboard -->|"reads URL"| node_runtime_config
node_dashboard -.->|"loads and subscribes"| node_live_client
node_audit_service -->|"serves and streams"| node_live_client
node_dashboard -.->|"seeds and subscribes"| node_demo_generator
node_dashboard -->|"supplies dashboard state"| node_dashboard_shell
node_dashboard -->|"passes events"| node_trend_overview
node_dashboard -->|"passes events"| node_producer_activity
node_dashboard -->|"passes events and filter"| node_audit_trail
node_reviewer -->|"requests verification"| node_verify_view
node_verify_view -->|"requests chain check"| node_live_client
node_dashboard -->|"supplies events"| node_alert_controls
node_alert_controls -->|"loads, saves, and evaluates"| node_alert_rules
node_trend_overview -->|"looks up severity"| node_rmf_catalog
node_producer_activity -->|"looks up severity"| node_rmf_catalog
node_trend_overview -->|"gets aggregates"| node_chart_derivations

click node_react_bootstrap "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/main.tsx"
click node_dashboard "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/App.tsx"
click node_live_client "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/audit-stream.ts"
click node_demo_generator "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/demo-events.ts"
click node_runtime_config "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/public/config.js"
click node_dashboard_shell "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/AppHeader.tsx"
click node_trend_overview "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/OverviewTab.tsx"
click node_producer_activity "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/ProducersTab.tsx"
click node_audit_trail "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/AuditTrailTab.tsx"
click node_verify_view "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/VerifyTab.tsx"
click node_rmf_catalog "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/rmf-citations.ts"
click node_chart_derivations "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/chart-utils.ts"
click node_alert_controls "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/NotificationBell.tsx"
click node_alert_rules "https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/alert-rules.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_react_bootstrap,node_dashboard,node_live_client,node_demo_generator,node_runtime_config,node_reviewer toneBlue
class node_dashboard_shell,node_trend_overview,node_producer_activity,node_audit_trail,node_verify_view toneAmber
class node_rmf_catalog,node_chart_derivations toneMint
class node_alert_controls,node_alert_rules toneRose
class node_audit_service toneIndigo
```

## Components

### Application and Event Input

- [React bootstrap](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/main.tsx): frontend entry point · `src/main.tsx`
- [Dashboard orchestrator](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/App.tsx): frontend application · `src/App.tsx`
- [Live audit client](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/audit-stream.ts): client library · `src/lib/audit-stream.ts`
- [Demo event generator](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/demo-events.ts): client library · `src/lib/demo-events.ts`
- [Runtime endpoint configuration](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/public/config.js): configuration · `public/config.js`

### Governance Views

- [Dashboard shell and status](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/AppHeader.tsx): UI component · `src/components/AppHeader.tsx`
- [Trend overview](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/OverviewTab.tsx): UI component · `src/components/OverviewTab.tsx`
- [Producer activity](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/ProducersTab.tsx): UI component · `src/components/ProducersTab.tsx`
- [Audit trail and vendor filtering](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/AuditTrailTab.tsx): UI component · `src/components/AuditTrailTab.tsx`
- [Chain verification view](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/VerifyTab.tsx): UI component · `src/components/VerifyTab.tsx`

### Event Interpretation

- [RMF event catalog](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/rmf-citations.ts): catalog · `src/lib/rmf-citations.ts`
- [Chart derivations](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/chart-utils.ts): utility · `src/lib/chart-utils.ts`

### Alerts

- [Alert controls and notifications](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/components/NotificationBell.tsx): UI component · `src/components/NotificationBell.tsx`
- [Alert rules and browser persistence](https://github.com/mizcausevic-dev/kg-governance-dashboard/blob/main/src/lib/alert-rules.ts): rules and persistence · Evaluates alert rules, persists rules and hits in browser localStorage, and handles desktop notifications. · `src/lib/alert-rules.ts`

### Other components

- **Reviewer**: external actor · Procurement reviewer, CISO, or district CIO.
- **Audit-stream service**: external service · Upstream service for event history, SSE events, and chain verification.

## Connections

- Reviewer → React bootstrap: opens dashboard
- React bootstrap → Dashboard orchestrator: renders
- Dashboard orchestrator → Runtime endpoint configuration: reads URL · The live client uses the runtime configuration lookup.
- Dashboard orchestrator → Live audit client: loads and subscribes · Used when a live URL is configured.
- Audit-stream service → Live audit client: serves and streams · Provides history and verification responses and sends SSE events.
- Dashboard orchestrator → Demo event generator: seeds and subscribes · Used when no live URL is configured.
- Dashboard orchestrator → Dashboard shell and status: supplies dashboard state
- Dashboard orchestrator → Trend overview: passes events
- Dashboard orchestrator → Producer activity: passes events
- Dashboard orchestrator → Audit trail and vendor filtering: passes events and filter
- Reviewer → Chain verification view: requests verification
- Chain verification view → Live audit client: requests chain check
- Dashboard orchestrator → Alert controls and notifications: supplies events
- Alert controls and notifications → Alert rules and browser persistence: loads, saves, and evaluates
- Trend overview → RMF event catalog: looks up severity
- Producer activity → RMF event catalog: looks up severity
- Trend overview → Chart derivations: gets aggregates