# mizcausevic-dev/vertical-benchmark-comparator architecture

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

## Overview

Purpose and principal workflow: Vertical Benchmark Comparator turns synthetic vertical-lane data into board-oriented comparisons of benchmark strength, evidence depth, commercial pull, repeatability, and execution drag. The main workflow begins when a board or executive user requests a page or JSON endpoint over HTTP; an operator can also initiate a separate analysis by running the CLI against a JSON file. The product is read-only and explicitly does not present its sample as live financial or investment advice.

Components

**HTTP presentation and routes**
- **Executive and board user** — Path: null (external actor). Initiates the main workflow by requesting a page or API response.
- **Express application** — Path: `src/app.ts`. Creates the Express app, maps the documented page and API routes, and starts listening when run directly.
- **Board-facing views** — Path: `src/services/render.ts`. Renders overview, register, comparison, investment, verification, and documentation pages as HTML, drawing on the report-data functions.
- **Prerendered site and API artifacts** — Path: `dist-static/index.html`. The README documents a prerendered static site with route-specific pages and JSON payloads; this tree establishes generated output exists, but not how it is served or deployed.

**Benchmark data and analysis**
- **Synthetic benchmark lanes** — Path: `src/data/sampleVerticalBrief.ts`. Supplies representative lane records with narrative, ownership, evidence, action, and score fields; the excerpt shows several sectors and is partial.
- **Benchmark analysis engine** — Path: `src/analyze.ts`. Assesses score strength and execution drag, computes composite priorities, and aggregates report-level counts, averages, revenue, and a leading message.
- **Benchmark data contract** — Path: `src/types.ts`. Defines the input lane, assessment, report, summary, and exported-payload shapes used by analysis and consumers.
- **Vertical brief projections** — Path: `src/services/verticalBriefService.ts`. Analyzes the sample at module initialization and exposes summary, register, matrix, investment, risk, verification, and combined-payload projections.

**Programmatic access**
- **CLI operator** — Path: null (external actor). Starts the separate command-line workflow by supplying an input JSON file and optional output format.
- **Analysis CLI** — Path: `src/cli.ts`. Reads and parses the supplied file, invokes the analysis engine, then emits JSON or a formatted text summary.
- **Summary formatter** — Path: `src/format.ts`. Converts report summary fields into the CLI’s human-readable, line-oriented output.
- **Library entry point** — Path: `src/index.ts`. Exports the analysis functions, sample data, and public types for programmatic consumers.

Relationships

- **Executive and board user -> Express application**: sends HTTP requests for pages or JSON; the app defines the routes and handles their responses.
- **Express application -> Board-facing views**: calls render functions for HTML routes.
- **Board-facing views -> Vertical brief projections**: calls projection functions to populate page content.
- **Express application -> Vertical brief projections**: calls projection functions for API responses.
- **Vertical brief projections -> Synthetic benchmark lanes**: reads the sample records to produce register, matrix, and payload data.
- **Vertical brief projections -> Benchmark analysis engine**: analyzes the sample and uses report results for summary, investment, and risk outputs.
- **Benchmark analysis engine -> Benchmark data contract**: uses the defined lane, assessment, and report shapes; the cited analysis code supplies the calculations.
- **CLI operator -> Analysis CLI**: invokes the command-line program with an input path and optional format.
- **Analysis CLI -> Benchmark analysis engine**: passes parsed lane records to `analyze`.
- **Analysis CLI -> Summary formatter**: passes the report summary for text output; JSON mode instead serializes the report directly.
- **Library entry point -> Benchmark analysis engine**: re-exports analysis functions for library consumers.
- **Library entry point -> Synthetic benchmark lanes**: re-exports the sample dataset.
- **Prerendered site and API artifacts**: the README documents prerender generation, but the sampled source does not establish the generation or deployment wiring.

Coverage limits: The excerpts do not include the prerender script, deployment workflow details, or the complete sample dataset. Therefore, the exact static-generation flow, hosting arrangement, and full lane coverage cannot be established here.

Main entry points: [`src/services/verticalBriefService.ts`](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/services/verticalBriefService.ts) (Vertical Brief Projections), [`src/analyze.ts`](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/analyze.ts) (Benchmark Analysis Engine), [`src/app.ts`](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/app.ts) (Express Application), [`src/cli.ts`](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/cli.ts) (Analysis CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP Presentation"]
  node_board_user(("Board User<br/>external actor"))
  node_express_app["Express Application<br/>HTTP app"]
  node_board_views["Board-Facing Views<br/>HTML rendering"]
  node_static_artifacts["Prerendered Artifacts<br/>generated output"]
end

subgraph group_analysis["Benchmark Analysis"]
  node_sample_lanes["Synthetic Benchmark Lanes<br/>sample data"]
  node_analysis_engine["Benchmark Analysis Engine<br/>analysis service"]
  node_data_contract["Benchmark Data Contract<br/>types"]
  node_brief_projections["Vertical Brief Projections<br/>projection service"]
end

subgraph group_programmatic["Programmatic Access"]
  node_cli_operator(("CLI Operator<br/>external actor"))
  node_analysis_cli["Analysis CLI<br/>[cli.ts]"]
  node_summary_formatter["Summary Formatter<br/>[format.ts]"]
  node_library_entry["Library Entry Point<br/>library exports"]
end

node_board_user -->|"HTTP requests"| node_express_app
node_express_app -->|"renders HTML"| node_board_views
node_board_views -->|"gets projections"| node_brief_projections
node_express_app -->|"gets API data"| node_brief_projections
node_brief_projections -->|"reads lanes"| node_sample_lanes
node_brief_projections -->|"analyzes sample"| node_analysis_engine
node_analysis_engine -->|"uses shapes"| node_data_contract
node_cli_operator -->|"runs CLI"| node_analysis_cli
node_analysis_cli -->|"analyzes records"| node_analysis_engine
node_analysis_cli -->|"formats summary"| node_summary_formatter
node_library_entry -->|"re-exports"| node_analysis_engine
node_library_entry -->|"re-exports"| node_sample_lanes

click node_express_app "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/app.ts"
click node_board_views "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/services/render.ts"
click node_static_artifacts "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/dist-static/index.html"
click node_sample_lanes "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/data/sampleVerticalBrief.ts"
click node_analysis_engine "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/analyze.ts"
click node_data_contract "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/types.ts"
click node_brief_projections "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/services/verticalBriefService.ts"
click node_analysis_cli "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/cli.ts"
click node_summary_formatter "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/format.ts"
click node_library_entry "https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/index.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_board_user,node_express_app,node_board_views,node_static_artifacts toneBlue
class node_sample_lanes,node_analysis_engine,node_data_contract,node_brief_projections toneAmber
class node_cli_operator,node_analysis_cli,node_summary_formatter,node_library_entry toneMint
```

## Components

### HTTP Presentation

- **Board User**: external actor
- [Express Application](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/app.ts): HTTP app · `src/app.ts`
- [Board-Facing Views](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/services/render.ts): HTML rendering · `src/services/render.ts`
- [Prerendered Artifacts](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/dist-static/index.html): generated output · Documented route-specific pages and JSON payloads; generation and serving wiring are unspecified. · `dist-static/index.html`

### Benchmark Analysis

- [Synthetic Benchmark Lanes](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/data/sampleVerticalBrief.ts): sample data · `src/data/sampleVerticalBrief.ts`
- [Benchmark Analysis Engine](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/analyze.ts): analysis service · `src/analyze.ts`
- [Benchmark Data Contract](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/types.ts): types · `src/types.ts`
- [Vertical Brief Projections](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/services/verticalBriefService.ts): projection service · `src/services/verticalBriefService.ts`

### Programmatic Access

- **CLI Operator**: external actor
- [Analysis CLI](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/cli.ts): CLI · `src/cli.ts`
- [Summary Formatter](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/format.ts): formatter · `src/format.ts`
- [Library Entry Point](https://github.com/mizcausevic-dev/vertical-benchmark-comparator/blob/main/src/index.ts): library exports · `src/index.ts`

## Connections

- Board User → Express Application: HTTP requests · Requests pages or JSON responses.
- Express Application → Board-Facing Views: renders HTML
- Board-Facing Views → Vertical Brief Projections: gets projections
- Express Application → Vertical Brief Projections: gets API data
- Vertical Brief Projections → Synthetic Benchmark Lanes: reads lanes
- Vertical Brief Projections → Benchmark Analysis Engine: analyzes sample
- Benchmark Analysis Engine → Benchmark Data Contract: uses shapes
- CLI Operator → Analysis CLI: runs CLI · Supplies an input JSON path and optional output format.
- Analysis CLI → Benchmark Analysis Engine: analyzes records
- Analysis CLI → Summary Formatter: formats summary · Used for text output; JSON mode serializes the report directly.
- Library Entry Point → Benchmark Analysis Engine: re-exports
- Library Entry Point → Synthetic Benchmark Lanes: re-exports