# hyperz111/npsze architecture

> Architecture diagram of the GitHub repository hyperz111/npsze, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperz111/npsze
- Repository: https://github.com/hyperz111/npsze

## Overview

npsze is an npm package-size checker, offered through a browser interface and a versioned JSON API. The main workflow takes a package name and optional version, resolves package metadata and a matching version, computes unpacked size (fetching and unpacking the archive when metadata lacks it), and recursively totals dependency sizes for the install estimate. The browser presents the result or an error. The README also documents version tags and ranges. Source excerpts show the principal runtime wiring; the production cache is shown, but the development store implementation was not inspected.

Main entry points: [`src/api/v0/core.ts`](https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts) (Metadata and version resolver), [`src/main.ts`](https://github.com/hyperz111/npsze/blob/main/src/main.ts) (Search and page state), [`src/api/v0/index.ts`](https://github.com/hyperz111/npsze/blob/main/src/api/v0/index.ts) (Package endpoint), [`src/elements.ts`](https://github.com/hyperz111/npsze/blob/main/src/elements.ts) (Results and suggestions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_browser["Search and page state<br/>[main.ts]"]
  node_presentation["Results and suggestions<br/>[elements.ts]"]
  node_dom["DOM helpers<br/>[html.ts]"]
end

subgraph group_api["API routing"]
  node_api_adapter["Netlify API adapter<br/>[function.ts]"]
  node_api_mount["API version mount<br/>[index.ts]"]
  node_v0_route["Package endpoint<br/>[index.ts]"]
end

subgraph group_analysis["Package analysis"]
  node_package_resolver["Metadata and version resolver<br/>[core.ts]"]
  node_archive_sizer["Archive unpack and sizing<br/>[core.ts]"]
  node_dependency_rollup["Dependency size rollup<br/>[core.ts]"]
end

subgraph group_state["Cached metadata"]
  node_metadata_cache[("Package metadata cache")]
end

node_user(("Package checker user"))
node_npm_registry["npm registry and tarballs"]

node_user -->|"enters package"| node_browser
node_browser -->|"renders states"| node_presentation
node_browser -->|"updates DOM"| node_dom
node_presentation -->|"builds elements"| node_dom
node_browser -->|"requests package"| node_v0_route
node_api_adapter -->|"serves app"| node_api_mount
node_api_mount -->|"mounts v0"| node_v0_route
node_v0_route -->|"resolves request"| node_package_resolver
node_package_resolver -->|"checks and stores"| node_metadata_cache
node_package_resolver -->|"fetches metadata"| node_npm_registry
node_package_resolver -->|"sizes missing data"| node_archive_sizer
node_archive_sizer -->|"fetches tarball"| node_npm_registry
node_dependency_rollup -->|"resolves dependencies"| node_package_resolver
node_v0_route -->|"returns size result"| node_dependency_rollup

click node_browser "https://github.com/hyperz111/npsze/blob/main/src/main.ts"
click node_presentation "https://github.com/hyperz111/npsze/blob/main/src/elements.ts"
click node_dom "https://github.com/hyperz111/npsze/blob/main/src/html.ts"
click node_api_adapter "https://github.com/hyperz111/npsze/blob/main/src/api/function.ts"
click node_api_mount "https://github.com/hyperz111/npsze/blob/main/src/api/index.ts"
click node_v0_route "https://github.com/hyperz111/npsze/blob/main/src/api/v0/index.ts"
click node_package_resolver "https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts"
click node_archive_sizer "https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts"
click node_dependency_rollup "https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts"
click node_metadata_cache "https://github.com/hyperz111/npsze/blob/main/src/api/v0/store-production.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_browser,node_presentation,node_dom,node_user toneBlue
class node_api_adapter,node_api_mount,node_v0_route toneAmber
class node_package_resolver,node_archive_sizer,node_dependency_rollup toneMint
class node_metadata_cache toneRose
class node_npm_registry toneIndigo
```

## Components

### Browser experience

- [Search and page state](https://github.com/hyperz111/npsze/blob/main/src/main.ts): `src/main.ts`
- [Results and suggestions](https://github.com/hyperz111/npsze/blob/main/src/elements.ts): `src/elements.ts`
- [DOM helpers](https://github.com/hyperz111/npsze/blob/main/src/html.ts): `src/html.ts`

### API routing

- [Netlify API adapter](https://github.com/hyperz111/npsze/blob/main/src/api/function.ts): `src/api/function.ts`
- [API version mount](https://github.com/hyperz111/npsze/blob/main/src/api/index.ts): `src/api/index.ts`
- [Package endpoint](https://github.com/hyperz111/npsze/blob/main/src/api/v0/index.ts): `src/api/v0/index.ts`

### Package analysis

- [Metadata and version resolver](https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts): `src/api/v0/core.ts`
- [Archive unpack and sizing](https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts): `src/api/v0/core.ts`
- [Dependency size rollup](https://github.com/hyperz111/npsze/blob/main/src/api/v0/core.ts): `src/api/v0/core.ts`

### Cached metadata

- [Package metadata cache](https://github.com/hyperz111/npsze/blob/main/src/api/v0/store-production.ts): `src/api/v0/store-production.ts`

### Other components

- **Package checker user**
- **npm registry and tarballs**

## Connections

- Package checker user → Search and page state: enters package (evidence: `README.md`)
- Search and page state → Results and suggestions: renders states (evidence: `src/main.ts`)
- Search and page state → DOM helpers: updates DOM (evidence: `src/main.ts`)
- Results and suggestions → DOM helpers: builds elements (evidence: `src/elements.ts`)
- Search and page state → Package endpoint: requests package (evidence: `src/main.ts`)
- Netlify API adapter → API version mount: serves app (evidence: `src/api/function.ts`)
- API version mount → Package endpoint: mounts v0 (evidence: `src/api/index.ts`)
- Package endpoint → Metadata and version resolver: resolves request (evidence: `src/api/v0/index.ts`)
- Metadata and version resolver → Package metadata cache: checks and stores (evidence: `src/api/v0/core.ts`)
- Metadata and version resolver → npm registry and tarballs: fetches metadata (evidence: `src/api/v0/core.ts`)
- Metadata and version resolver → Archive unpack and sizing: sizes missing data (evidence: `src/api/v0/core.ts`)
- Archive unpack and sizing → npm registry and tarballs: fetches tarball (evidence: `src/api/v0/core.ts`)
- Dependency size rollup → Metadata and version resolver: resolves dependencies (evidence: `src/api/v0/core.ts`)
- Package endpoint → Dependency size rollup: returns size result (evidence: `src/api/v0/index.ts`)