# mizcausevic-dev/shadow-ai-detector architecture

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

## Overview

Shadow AI Detector is a deterministic TypeScript/Express API for identifying enterprise traffic to known LLM endpoints, scanning request payload snippets for sensitive material, scoring event and fleet risk, and reporting department exposure and incidents. The documented main workflow is initiated by an enterprise proxy/firewall traffic source sending captured events to the API; the sampled implementation analyzes events supplied by API callers and also exposes reports calculated from a built-in demo dataset. Live proxy ingestion and automated enforcement are not established.

Components

**HTTP application**
- **API server** — `src/index.ts`: Creates the Express app, installs middleware, serves health status, and mounts endpoint, analysis, incident, and dashboard routers. It listens on the configured port when run as the main module.
- **API request handlers** — `src/routes/index.ts`: Implements the documented REST routes, validates analysis requests, calls governance functions, and returns catalog, assessment, incident, and dashboard responses.
- **Request schemas** — `src/schemas/validation-schemas.ts`: Defines Zod validation for endpoint classification, payload scans, and single or bulk traffic assessments.

**Detection and exposure analysis**
- **Endpoint classifier** — `src/governance/endpoint-classifier.ts`: Matches URL hosts and paths against a catalog of LLM endpoints and returns provider, capability, risk, and country metadata; also supports listing endpoints and determining sanction status.
- **Payload scanner** — `src/governance/payload-scanner.ts`: Applies regex patterns for credentials, PII, payment data, health data, internal markers, and source-code secrets; returns severity and redacted match snippets.
- **Event and fleet risk scorer** — `src/governance/risk-scorer.ts`: Combines endpoint classification, sanction status, payload hits, and upload volume into per-event risk verdicts, then aggregates fleet summaries and top-risk users.
- **Department exposure rollup** — `src/governance/department-rollup.ts`: Aggregates aligned events and assessments by department into usage, tier, provider, sanction-rate, exposure-score, and recommended-action metrics.

**Catalog and report data**
- **Endpoint and sanction catalog** — `src/data/endpoints.ts`: Holds the demo organization’s sanctioned endpoint IDs and provider metadata used in catalog and dashboard responses.
- **Demo traffic dataset** — `src/data/traffic.ts`: Supplies representative proxy-style events used by dashboard summaries and exposure reports; this is sample data, not evidence of a connected traffic feed.
- **Incident register** — `src/data/incidents.ts`: Defines the in-memory incident records and their status, severity, ownership, and recommended actions; sampled routes read and filter these records.

Relationships

- **Enterprise proxy/firewall traffic source** (external; repository path: null) -> **API server**: documented as the traffic origin; live source integration is not shown.
- **API server** -> **API request handlers**: mounts routers for endpoint, analysis, incident, and dashboard routes.
- **API request handlers** -> **Request schemas**: validates request bodies with `safeParse` before analysis calls.
- **API request handlers** -> **Endpoint classifier**: classifies submitted URLs and lists catalog entries.
- **API request handlers** -> **Payload scanner**: scans submitted payloads directly on the payload-analysis route.
- **API request handlers** -> **Event and fleet risk scorer**: assesses a single submitted event or a submitted event batch; dashboard handlers also score demo events.
- **Event and fleet risk scorer** -> **Endpoint classifier**: classifies each event URL and resolves sanction status.
- **Event and fleet risk scorer** -> **Payload scanner**: scans each event’s payload snippet and incorporates findings into its verdict.
- **API request handlers** -> **Department exposure rollup**: passes submitted events and fleet assessments for bulk analysis; dashboard handlers pass demo events and assessments.
- **API request handlers** -> **Endpoint and sanction catalog**: reads sanctioned IDs and provider metadata for catalog and dashboard responses.
- **API request handlers** -> **Demo traffic dataset**: reads events for dashboard summary and exposure calculations.
- **API request handlers** -> **Incident register**: reads and filters incidents for incident and dashboard routes.
- **Enterprise API consumer** (external; repository path: null) -> **API server**: calls the documented HTTP endpoints; this is the implemented interface for supplying events and retrieving results.
- **API server** -> **Enterprise API consumer**: returns JSON responses, including event verdicts, fleet summaries, department exposure, catalog, and incident data.

Coverage limits

The source excerpts establish route wiring and core analysis flow, but do not show the full endpoint catalog or all classifier logic. The README documents a 30+ endpoint catalog and additional reporting behavior; sampled data is in-memory, and no persistence, live proxy/firewall connector, or egress-blocking integration is shown. The dashboard preview file is present, but its behavior is not established by the sampled source.

Main entry points: [`src/routes/index.ts`](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/routes/index.ts) (API Request Handlers), [`src/index.ts`](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/index.ts) (API Server), [`src/governance/risk-scorer.ts`](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/risk-scorer.ts) (Event and Fleet Risk Scorer), [`src/governance/endpoint-classifier.ts`](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/endpoint-classifier.ts) (Endpoint Classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP Application"]
  node_server["API Server<br/>Express app"]
  node_handlers["API Request Handlers<br/>REST routes"]
  node_schemas["Request Schemas<br/>Zod validation"]
end

subgraph group_analysis["Detection and Exposure Analysis"]
  node_classifier["Endpoint Classifier<br/>LLM endpoint matching"]
  node_scanner["Payload Scanner<br/>Sensitive-data scanning"]
  node_scorer["Event and Fleet Risk Scorer<br/>Risk analysis"]
  node_rollup["Department Exposure Rollup<br/>Exposure aggregation"]
end

subgraph group_data["Catalog and Report Data"]
  node_catalog["Endpoint and Sanction Catalog<br/>Catalog data"]
  node_traffic["Demo Traffic Dataset<br/>Sample events"]
  node_incidents["Incident Register<br/>In-memory incident records"]
end

node_proxy["Enterprise Proxy/Firewall<br/>External traffic source"]
node_consumer["Enterprise API Consumer<br/>External client"]

node_proxy -.->|"traffic origin"| node_server
node_consumer -->|"HTTP requests"| node_server
node_server -->|"JSON responses"| node_consumer
node_server -->|"mounts routers"| node_handlers
node_handlers -->|"validates requests"| node_schemas
node_handlers -->|"classifies URLs"| node_classifier
node_handlers -->|"scans payloads"| node_scanner
node_handlers -->|"assesses events"| node_scorer
node_handlers -->|"rolls up exposure"| node_rollup
node_scorer -->|"classifies events"| node_classifier
node_scorer -->|"scans event payloads"| node_scanner
node_handlers -->|"reads catalog"| node_catalog
node_handlers -->|"reads demo events"| node_traffic
node_handlers -->|"reads incidents"| node_incidents

click node_server "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/index.ts"
click node_handlers "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/routes/index.ts"
click node_schemas "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/schemas/validation-schemas.ts"
click node_classifier "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/endpoint-classifier.ts"
click node_scanner "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/payload-scanner.ts"
click node_scorer "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/risk-scorer.ts"
click node_rollup "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/department-rollup.ts"
click node_catalog "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/data/endpoints.ts"
click node_traffic "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/data/traffic.ts"
click node_incidents "https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/data/incidents.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_server,node_handlers,node_schemas,node_consumer toneBlue
class node_classifier,node_scanner,node_scorer,node_rollup toneAmber
class node_catalog,node_traffic,node_incidents toneMint
class node_proxy toneIndigo
```

## Components

### HTTP Application

- [API Server](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/index.ts): Express app · `src/index.ts`
- [API Request Handlers](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/routes/index.ts): REST routes · `src/routes/index.ts`
- [Request Schemas](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/schemas/validation-schemas.ts): Zod validation · `src/schemas/validation-schemas.ts`

### Detection and Exposure Analysis

- [Endpoint Classifier](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/endpoint-classifier.ts): LLM endpoint matching · `src/governance/endpoint-classifier.ts`
- [Payload Scanner](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/payload-scanner.ts): Sensitive-data scanning · `src/governance/payload-scanner.ts`
- [Event and Fleet Risk Scorer](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/risk-scorer.ts): Risk analysis · `src/governance/risk-scorer.ts`
- [Department Exposure Rollup](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/governance/department-rollup.ts): Exposure aggregation · `src/governance/department-rollup.ts`

### Catalog and Report Data

- [Endpoint and Sanction Catalog](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/data/endpoints.ts): Catalog data · `src/data/endpoints.ts`
- [Demo Traffic Dataset](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/data/traffic.ts): Sample events · In-memory sample data, not a connected traffic feed. · `src/data/traffic.ts`
- [Incident Register](https://github.com/mizcausevic-dev/shadow-ai-detector/blob/main/src/data/incidents.ts): In-memory incident records · `src/data/incidents.ts`

### Other components

- **Enterprise Proxy/Firewall**: External traffic source · Documented traffic origin; live integration is not shown.
- **Enterprise API Consumer**: External client

## Connections

- Enterprise Proxy/Firewall → API Server: traffic origin · Live source integration is not shown.
- Enterprise API Consumer → API Server: HTTP requests
- API Server → Enterprise API Consumer: JSON responses
- API Server → API Request Handlers: mounts routers
- API Request Handlers → Request Schemas: validates requests
- API Request Handlers → Endpoint Classifier: classifies URLs
- API Request Handlers → Payload Scanner: scans payloads
- API Request Handlers → Event and Fleet Risk Scorer: assesses events
- API Request Handlers → Department Exposure Rollup: rolls up exposure
- Event and Fleet Risk Scorer → Endpoint Classifier: classifies events
- Event and Fleet Risk Scorer → Payload Scanner: scans event payloads
- API Request Handlers → Endpoint and Sanction Catalog: reads catalog
- API Request Handlers → Demo Traffic Dataset: reads demo events
- API Request Handlers → Incident Register: reads incidents