# mizcausevic-dev/codebase-bloat-tax architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/codebase-bloat-tax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/codebase-bloat-tax
- Repository: https://github.com/mizcausevic-dev/codebase-bloat-tax

## Overview

#### Purpose and principal workflow

Codebase Bloat & Technical Debt Tax is a local-first React decision-support app that turns JavaScript manifests, lockfiles, optional build/CI artifacts, and import snippets into a labeled report of dependency, bundle, security, and delivery-cost signals. A developer or engineering lead initiates an analysis in the browser by uploading files, supplying a public GitHub URL, entering an import snippet, choosing a screenshot, or loading the demo. The app builds a dependency graph, optionally enriches it with external lookups, computes estimates and recommendations, validates the report, and presents it for review or export.

#### Components

##### Browser application and input
- **Browser React entry point** — `src/main.tsx`: mounts the React application into the page root.
- **Application coordinator** — `src/App.tsx`: owns the report, busy/error and operator-configuration state; calls the analysis workflow and coordinates report display and export actions.
- **Ingestion interface** — `src/ui/dashboard/IngestView.tsx`: offers upload, public-repository, snippet, screenshot/OCR, and demo entry paths and forwards their parsed inputs for analysis.
- **Input validation and safety** — `src/ingestion/validate.ts`: enforces filename, size, paste, URL, JSON-depth, and forbidden-key constraints used when accepting untrusted input.
- **Input acquisition and parsing** — `src/ingestion/manifests.ts`: provides manifest/file and import-snippet ingestion; README also documents separate screenshot OCR and GitHub Contents ingestion paths.
- **Public GitHub ingestion** — `src/ingestion/github.ts`: documented and imported as the public repository manifest fetcher; exact request details are not in the sampled excerpt.
- **Screenshot OCR** — `src/ingestion/screenshots.ts`: imported by the ingestion UI to extract package names from images; README says OCR runs in-browser.

##### Dependency and evidence processing
- **Dependency graph resolution** — `src/graph/resolveNpm.ts`: parses npm lockfiles into nodes and dependency edges with a node safety cap; pnpm and Yarn have separate resolver modules in the same graph subsystem.
- **Graph normalization and report shaping** — `src/graph/normalize.ts`: imported by the analysis workflow to normalize and serialize dependency graph data for the report.
- **Build and CI artifact parsing** — `src/analysis/artifacts.ts`: imported to parse bundler artifacts, Lighthouse data, and CI timestamps as distinct evidence inputs.
- **External intelligence lookups** — `src/intelligence/vulnerabilities.ts`: queries OSV for resolved package versions, validates responses, caches results, and reports lookup status; analysis also imports separate npm Registry and Bundlephobia lookups.

##### Analysis and output
- **Analysis orchestration** — `src/analysis/runAnalysis.ts`: parses evidence, optionally runs intelligence lookups, invokes estimate/recommendation models, and assembles the report.
- **Decision and estimate models** — `src/models/bundleImpact.ts`: computes bundle-impact estimates, preferring artifact measurements and modeling transfer time from configured network profiles; the analysis workflow also invokes separate mobile, build-wait, opportunity-cost, and alternatives models.
- **Report contract** — `src/schemas/report.ts`: defines Zod-validated report structures for estimates, graph data, recommendations, security findings, and lookup status.
- **Analysis dashboard** — `src/ui/dashboard/Dashboard.tsx`: report presentation surface, documented by the README as including evidence and recommendations; specific rendering details were not sampled.
- **Markdown export** — `src/export/markdown.ts`: creates PR-safe report notes, supports package-name privacy options, and redacts likely secrets, emails, and absolute paths.
- **Workflow preview generation** — `src/export/githubAction.ts`: imported by the application to generate a GitHub Action file for preview; it does not automatically commit or write a workflow.

##### Optional private-repository path
- **Private GitHub OAuth function** — `netlify/functions/github-oauth.ts`: exchanges an OAuth code and fetches an allowlisted set of repository files using a read token held in memory for the request.
- **Developer / engineering lead** — `null`: external browser user who supplies analysis inputs and reviews or exports the result.
- **GitHub Contents API** — `null`: external API used for public repository ingestion and, on a configured server host, private repository reads.
- **Lookup providers** — `null`: external npm Registry, Bundlephobia, and OSV services used for optional package metadata, advisory size estimates, and vulnerability findings.

#### Relationships

- **Developer / engineering lead -> Browser React entry point**: opens the browser app; README describes a local-first React app and public preview.
- **Browser React entry point -> Application coordinator**: mounts the React application; the entry module imports and renders it.
- **Application coordinator -> Ingestion interface**: presents input paths and receives their analysis payloads; the app renders the ingest view and coordinates analysis.
- **Ingestion interface -> Input acquisition and parsing**: ingests uploaded text and parses import snippets; shown by its imports and handlers.
- **Ingestion interface -> Public GitHub ingestion**: requests public repository manifests on URL submission; shown by the imported fetcher and handler.
- **Ingestion interface -> Screenshot OCR**: sends an image for OCR and forwards extracted package names; shown by the screenshot handler.
- **Input acquisition and parsing -> Input validation and safety**: validates accepted text and filenames; README documents enforced input limits and source imports validation errors.
- **Public GitHub ingestion -> GitHub Contents API**: fetches manifests from public repositories; the UI identifies the unauthenticated Contents API as the source.
- **Application coordinator -> Analysis orchestration**: calls analysis with the submitted payload and operator configuration; shown by the analysis call.
- **Analysis orchestration -> Dependency graph resolution**: resolves dependency data from the supplied lockfile; README documents the ingestion-to-graph pipeline, with npm resolver behavior shown in its source.
- **Analysis orchestration -> Build and CI artifact parsing**: parses bundler, Lighthouse, and CI evidence before estimate generation; shown by the imported parser calls.
- **Analysis orchestration -> External intelligence lookups**: conditionally invokes Bundlephobia, npm Registry, and vulnerability lookups when enabled; shown by the parallel lookup calls.
- **External intelligence lookups -> Lookup providers**: queries OSV for package/version advisories; the vulnerability module calls `api.osv.dev`. Registry and Bundlephobia calls are documented/imported, but their concrete request details were not sampled.
- **Analysis orchestration -> Decision and estimate models**: passes artifacts, lookup results, and operator settings into estimate and recommendation calculations; shown by model calls.
- **Analysis orchestration -> Report contract**: validates the assembled report with the report schema; shown by the schema import and README’s documented Zod contract.
- **Analysis orchestration -> Graph normalization and report shaping**: converts the normalized graph to report form; shown by `graphToReportShape`.
- **Application coordinator -> Analysis dashboard**: supplies the completed report for display; the app owns report state and renders the dashboard.
- **Application coordinator -> Markdown export**: provides report export actions; the app imports the Markdown export module, though the call site was not included in the excerpt.
- **Application coordinator -> Workflow preview generation**: generates and displays workflow text from the report’s package-manager information; shown by the workflow handler.
- **Developer / engineering lead -> Private GitHub OAuth function**: may initiate a private Contents: read flow when hosted and enabled; README documents the server-only path, while the preview disables it.
- **Private GitHub OAuth function -> GitHub Contents API**: exchanges the OAuth code and requests allowlisted repository files with the resulting bearer token; shown by the function’s fetch calls.

#### Coverage limits

Several source excerpts are partial, so exact ordering and error handling inside the full analysis and UI are not established. The README documents separate pnpm/Yarn resolvers, lookup caching, and localStorage preference/history behavior, but the sampled sources do not establish their detailed call paths or persistence behavior. The private OAuth function is present, but its client-side invocation is not shown; its use is documented as conditional on server hosting and configuration.

Main entry points: [`src/analysis/runAnalysis.ts`](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/analysis/runAnalysis.ts) (Analysis orchestration), [`src/App.tsx`](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/App.tsx) (Application coordinator), [`src/ui/dashboard/IngestView.tsx`](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ui/dashboard/IngestView.tsx) (Ingestion interface), [`src/main.tsx`](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/main.tsx) (React entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser application"]
  node_entry["React entry point<br/>Browser entry"]
  node_app["Application coordinator<br/>React app"]
  node_ingest_ui["Ingestion interface<br/>UI"]
end

subgraph group_ingestion["Input and ingestion"]
  node_acquisition["Input acquisition<br/>Ingestion"]
  node_validation["Input validation<br/>Safety"]
  node_github_ingest["Public GitHub ingestion<br/>[github.ts]"]
  node_screenshot["Screenshot OCR<br/>Ingestion"]
end

subgraph group_processing["Dependency and evidence processing"]
  node_graph_resolve["Dependency graph resolution<br/>Resolver"]
  node_graph_normalize["Graph normalization<br/>Report shaping"]
  node_artifacts["Artifact parsing<br/>Evidence parser"]
  node_intelligence["External intelligence lookups<br/>Lookup service"]
end

subgraph group_analysis["Analysis and output"]
  node_analysis_run["Analysis orchestration<br/>Workflow"]
  node_models["Decision and estimate models<br/>[bundleImpact.ts]"]
  node_report["Report contract<br/>Schema"]
  node_dashboard["Analysis dashboard<br/>UI"]
  node_markdown["Markdown export<br/>Exporter"]
  node_workflow_preview["Workflow preview<br/>Exporter"]
end

subgraph group_private["Private repository path"]
  node_private_oauth["Private GitHub OAuth<br/>Server function"]
end

node_developer["Developer / lead<br/>External user"]
node_github_api["GitHub Contents API<br/>External API"]
node_providers["Lookup providers<br/>External services"]

node_developer -->|"opens"| node_entry
node_entry -->|"mounts"| node_app
node_app -->|"presents inputs"| node_ingest_ui
node_ingest_ui -->|"parses inputs"| node_acquisition
node_ingest_ui -->|"fetches manifests"| node_github_ingest
node_ingest_ui -->|"extracts packages"| node_screenshot
node_acquisition -->|"validates input"| node_validation
node_github_ingest -->|"fetches manifests"| node_github_api
node_app -->|"runs analysis"| node_analysis_run
node_analysis_run -->|"resolves dependencies"| node_graph_resolve
node_analysis_run -->|"parses evidence"| node_artifacts
node_analysis_run -.->|"runs lookups"| node_intelligence
node_intelligence -->|"queries packages"| node_providers
node_analysis_run -->|"computes estimates"| node_models
node_analysis_run -->|"validates report"| node_report
node_analysis_run -->|"shapes graph"| node_graph_normalize
node_app -->|"displays report"| node_dashboard
node_app -->|"exports report"| node_markdown
node_app -->|"generates preview"| node_workflow_preview
node_developer -.->|"requests private access"| node_private_oauth
node_private_oauth -.->|"reads repository files"| node_github_api

click node_entry "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/main.tsx"
click node_app "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/App.tsx"
click node_ingest_ui "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ui/dashboard/IngestView.tsx"
click node_acquisition "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/manifests.ts"
click node_validation "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/validate.ts"
click node_github_ingest "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/github.ts"
click node_screenshot "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/screenshots.ts"
click node_graph_resolve "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/graph/resolveNpm.ts"
click node_graph_normalize "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/graph/normalize.ts"
click node_artifacts "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/analysis/artifacts.ts"
click node_intelligence "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/intelligence/vulnerabilities.ts"
click node_analysis_run "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/analysis/runAnalysis.ts"
click node_models "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/models/bundleImpact.ts"
click node_report "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/schemas/report.ts"
click node_dashboard "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ui/dashboard/Dashboard.tsx"
click node_markdown "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/export/markdown.ts"
click node_workflow_preview "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/export/githubAction.ts"
click node_private_oauth "https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/netlify/functions/github-oauth.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_entry,node_app,node_ingest_ui,node_developer toneBlue
class node_acquisition,node_validation,node_github_ingest,node_screenshot toneAmber
class node_graph_resolve,node_graph_normalize,node_artifacts,node_intelligence,node_github_api toneMint
class node_analysis_run,node_models,node_report,node_dashboard,node_markdown,node_workflow_preview toneRose
class node_private_oauth,node_providers toneIndigo
```

## Components

### Browser application

- [React entry point](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/main.tsx): Browser entry · `src/main.tsx`
- [Application coordinator](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/App.tsx): React app · `src/App.tsx`
- [Ingestion interface](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ui/dashboard/IngestView.tsx): UI · `src/ui/dashboard/IngestView.tsx`

### Input and ingestion

- [Input acquisition](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/manifests.ts): Ingestion · `src/ingestion/manifests.ts`
- [Input validation](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/validate.ts): Safety · `src/ingestion/validate.ts`
- [Public GitHub ingestion](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/github.ts): Ingestion · `src/ingestion/github.ts`
- [Screenshot OCR](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ingestion/screenshots.ts): Ingestion · `src/ingestion/screenshots.ts`

### Dependency and evidence processing

- [Dependency graph resolution](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/graph/resolveNpm.ts): Resolver · `src/graph/resolveNpm.ts`
- [Graph normalization](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/graph/normalize.ts): Report shaping · `src/graph/normalize.ts`
- [Artifact parsing](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/analysis/artifacts.ts): Evidence parser · `src/analysis/artifacts.ts`
- [External intelligence lookups](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/intelligence/vulnerabilities.ts): Lookup service · `src/intelligence/vulnerabilities.ts`

### Analysis and output

- [Analysis orchestration](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/analysis/runAnalysis.ts): Workflow · `src/analysis/runAnalysis.ts`
- [Decision and estimate models](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/models/bundleImpact.ts): Models · `src/models/bundleImpact.ts`
- [Report contract](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/schemas/report.ts): Schema · `src/schemas/report.ts`
- [Analysis dashboard](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/ui/dashboard/Dashboard.tsx): UI · `src/ui/dashboard/Dashboard.tsx`
- [Markdown export](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/export/markdown.ts): Exporter · `src/export/markdown.ts`
- [Workflow preview](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/src/export/githubAction.ts): Exporter · `src/export/githubAction.ts`

### Private repository path

- [Private GitHub OAuth](https://github.com/mizcausevic-dev/codebase-bloat-tax/blob/main/netlify/functions/github-oauth.ts): Server function · `netlify/functions/github-oauth.ts`

### Other components

- **Developer / lead**: External user
- **GitHub Contents API**: External API
- **Lookup providers**: External services

## Connections

- Developer / lead → React entry point: opens
- React entry point → Application coordinator: mounts
- Application coordinator → Ingestion interface: presents inputs
- Ingestion interface → Input acquisition: parses inputs
- Ingestion interface → Public GitHub ingestion: fetches manifests
- Ingestion interface → Screenshot OCR: extracts packages
- Input acquisition → Input validation: validates input
- Public GitHub ingestion → GitHub Contents API: fetches manifests
- Application coordinator → Analysis orchestration: runs analysis
- Analysis orchestration → Dependency graph resolution: resolves dependencies
- Analysis orchestration → Artifact parsing: parses evidence
- Analysis orchestration → External intelligence lookups: runs lookups
- External intelligence lookups → Lookup providers: queries packages
- Analysis orchestration → Decision and estimate models: computes estimates
- Analysis orchestration → Report contract: validates report
- Analysis orchestration → Graph normalization: shapes graph
- Application coordinator → Analysis dashboard: displays report
- Application coordinator → Markdown export: exports report
- Application coordinator → Workflow preview: generates preview
- Developer / lead → Private GitHub OAuth: requests private access
- Private GitHub OAuth → GitHub Contents API: reads repository files