# mizcausevic-dev/identity-cost-drift-brief architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/identity-cost-drift-brief, 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/identity-cost-drift-brief
- Repository: https://github.com/mizcausevic-dev/identity-cost-drift-brief

## Overview

#### Purpose and principal workflow

Identity Cost Drift Brief is a read-only executive-intelligence product for summarizing identity-spend drift, license waste, control duplication, and remediation priorities from synthetic lane data. In the main web workflow, an external HTTP client requests a page or JSON endpoint; the Express app obtains a view of the modeled data and returns rendered HTML or JSON. A separate CLI workflow lets a command-line user analyze a supplied JSON file and receive summary text or a JSON report.

#### Components

##### Web surface
- **HTTP client** — *null repository path*. External actor that initiates the main workflow by requesting a page or API route.
- **Express routes and server** — `src/app.ts`. Creates the Express app, maps page and API routes, and starts a listener when run directly; page handlers send HTML and API handlers send JSON.
- **Executive views** — `src/services/render.ts`. Builds the overview, drift-register, cost-tier, remediation, verification, and docs pages as HTML, drawing on the brief service’s outputs.

##### Analysis and modeled brief
- **Brief analysis** — `src/analyze.ts`. Applies thresholds to each lane’s drift, waste, review burden, duplication, and control-gap scores; computes per-lane recovery scores and report-level summary metrics.
- **Sample identity-cost lanes** — `src/data/sampleVerticalBrief.ts`. Defines the synthetic lane inputs, including owners, audiences, scores, narratives, and proposed next moves.
- **Brief data and view shaping** — `src/services/verticalBriefService.ts`. Analyzes the sample at module initialization and exposes summary, register, cost-tier, remediation, risk-map, verification, and combined-payload results.
- **Domain contracts** — `src/types.ts`. Defines the lane, assessment, report, summary, and payload shapes used across analysis and exports.

##### CLI and distribution
- **CLI user** — *null repository path*. External actor who invokes the documented command with an input file and optional output format.
- **Command-line entry point** — `src/cli.ts`. Reads and parses the selected JSON file, calls the analyzer, and prints either JSON or a formatted summary.
- **Summary formatter** — `src/format.ts`. Converts report summary metrics into the CLI’s human-readable text output.
- **Static site and API artifacts** — `dist-static/index.html`. The repository includes a prerendered static site and JSON artifacts under `dist-static`; the README documents prerendering, but the sampled source does not establish how those artifacts are generated or published.

#### Relationships

- **HTTP client -> Express routes and server**: sends page or API requests; the route handlers are defined in the app.
- **Express routes and server -> Executive views**: calls the corresponding renderer for HTML page responses.
- **Express routes and server -> Brief data and view shaping**: calls the relevant exports for JSON API responses.
- **Executive views -> Brief data and view shaping**: calls summary, register, cost-tier, remediation, risk-map, verification, and payload exports while building pages.
- **Brief data and view shaping -> Sample identity-cost lanes**: reads the synthetic lane array to construct register and cost-tier outputs.
- **Brief data and view shaping -> Brief analysis**: analyzes the sample to create the report used for summary, remediation, and risk-map outputs.
- **Brief analysis -> Domain contracts**: produces report and assessment values with the declared domain shapes.
- **CLI user -> Command-line entry point**: invokes the CLI with a JSON input path and optional format, as documented in the README.
- **Command-line entry point -> Brief analysis**: passes parsed input items to the analyzer.
- **Command-line entry point -> Summary formatter**: formats the report summary when text output is selected.
- **Command-line entry point -> Domain contracts**: interprets parsed input as lane items and uses the analyzer’s report summary.
- **Static site and API artifacts -> Brief data and view shaping**: ownership or generation relationship only; the sampled source does not establish a runtime interaction or artifact-generation data flow.

#### Coverage limits

The sampled files establish the Express route handlers, analysis logic, sample data, and CLI flow. The README documents prerendered output, but the prerender script, deployment behavior, and any live Kinetic Gain data connection were not established; the verification output explicitly describes the data as synthetic and the routes as read-only.

Main entry points: [`src/cli.ts`](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/cli.ts) (CLI entry point), [`src/services/verticalBriefService.ts`](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/services/verticalBriefService.ts) (Brief view shaping), [`src/app.ts`](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/app.ts) (Express routes), [`src/analyze.ts`](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/analyze.ts) (Brief analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web surface"]
  node_http_client(("HTTP client<br/>external actor"))
  node_express_app["Express routes<br/>server"]
  node_executive_views["Executive views<br/>renderer"]
end

subgraph group_analysis["Analysis and modeled brief"]
  node_brief_service["Brief view shaping"]
  node_sample_lanes["Sample identity-cost lanes<br/>synthetic data"]
  node_brief_analysis["Brief analysis<br/>analyzer"]
  node_domain_contracts["Domain contracts<br/>data shapes"]
end

subgraph group_cli["CLI"]
  node_cli_user(("CLI user<br/>external actor"))
  node_cli_entry["CLI entry point<br/>command-line interface"]
  node_summary_formatter["Summary formatter<br/>[format.ts]"]
end

node_http_client -->|"sends requests"| node_express_app
node_express_app -->|"renders pages"| node_executive_views
node_express_app -->|"serves API"| node_brief_service
node_executive_views -->|"uses exports"| node_brief_service
node_brief_service -->|"reads lanes"| node_sample_lanes
node_brief_service -->|"analyzes sample"| node_brief_analysis
node_brief_analysis -->|"produces values"| node_domain_contracts
node_cli_user -->|"invokes CLI"| node_cli_entry
node_cli_entry -->|"analyzes input"| node_brief_analysis
node_cli_entry -->|"formats summary"| node_summary_formatter
node_cli_entry -->|"uses shapes"| node_domain_contracts

click node_express_app "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/app.ts"
click node_executive_views "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/services/render.ts"
click node_brief_service "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/services/verticalBriefService.ts"
click node_sample_lanes "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/data/sampleVerticalBrief.ts"
click node_brief_analysis "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/analyze.ts"
click node_domain_contracts "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/types.ts"
click node_cli_entry "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/cli.ts"
click node_summary_formatter "https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/format.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_http_client,node_express_app,node_executive_views toneBlue
class node_brief_service,node_sample_lanes,node_brief_analysis,node_domain_contracts toneAmber
class node_cli_user,node_cli_entry,node_summary_formatter toneMint
```

## Components

### Web surface

- **HTTP client**: external actor
- [Express routes](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/app.ts): server · `src/app.ts`
- [Executive views](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/services/render.ts): renderer · `src/services/render.ts`

### Analysis and modeled brief

- [Brief view shaping](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/services/verticalBriefService.ts): service · `src/services/verticalBriefService.ts`
- [Sample identity-cost lanes](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/data/sampleVerticalBrief.ts): synthetic data · `src/data/sampleVerticalBrief.ts`
- [Brief analysis](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/analyze.ts): analyzer · `src/analyze.ts`
- [Domain contracts](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/types.ts): data shapes · `src/types.ts`

### CLI

- **CLI user**: external actor
- [CLI entry point](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/cli.ts): command-line interface · `src/cli.ts`
- [Summary formatter](https://github.com/mizcausevic-dev/identity-cost-drift-brief/blob/main/src/format.ts): formatter · `src/format.ts`

## Connections

- HTTP client → Express routes: sends requests
- Express routes → Executive views: renders pages
- Express routes → Brief view shaping: serves API
- Executive views → Brief view shaping: uses exports
- Brief view shaping → Sample identity-cost lanes: reads lanes
- Brief view shaping → Brief analysis: analyzes sample
- Brief analysis → Domain contracts: produces values
- CLI user → CLI entry point: invokes CLI
- CLI entry point → Brief analysis: analyzes input
- CLI entry point → Summary formatter: formats summary
- CLI entry point → Domain contracts: uses shapes