# equalma/gitpkg architecture

> Architecture diagram of the GitHub repository equalma/gitpkg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/equalma/gitpkg
- Repository: https://github.com/equalma/gitpkg

## Overview

##### Main High-Level Components
a. Monorepo (single codebase)
- packages/core
- packages/edge-polyfill
- api (serverless functions)
- website (Docusaurus React site)
b. Deployment Platform
- Vercel (serverless / edge runtime)
c. External Services
- GitHub (source repos, raw file/tarball URLs)
- npm / yarn client (consumes packaged subfolders)

##### Relationships & Data Flows
- Developer / CI (GitHub Actions, Husky hooks) pushes code → Vercel deploys “api/” functions and “website/”.
- End user (npm client) runs `npm install gitpkg:owner/repo/path` → resolves to GitPkg API endpoint on Vercel.
- API function (e.g. pkg.ts) invokes core logic in packages/core:
– calls GitHub APIs or raw URLs to fetch the entire repo tarball
– uses parse-url-query to interpret path, commit-ish, custom scripts plugin
– uses tar utilities to extract the subfolder and re-package it
– streams the resulting tarball back to the npm client
– edge-polyfill ensures Node-style streams work in edge runtime
- Website UI (React/Docusaurus) fetches live demos / ping endpoints from the same API to demonstrate usage.

##### Architectural Patterns & Key Principles
- Monorepo with shared TypeScript configurations (tsconfig.base.json)
- Code reuse: api/ imports packages/core and edge-polyfill
- Serverless / Edge functions: each file in api/ folder = separate endpoint
- Static site generation (SSG) + client-side React for docs/demo
- Polyfill layer for Web Streams API on edge runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Presentation Layer"
    Website["Frontend Website\n(Docusaurus + React)"]:::ui
  end

  subgraph "Application Layer (Vercel Cloud)"
    subgraph "Serverless API Layer"
      ping["ping.ts – health check"]:::compute
      pkg["pkg.ts – builds subfolder tarball"]:::compute
      pkgurl["pkg-from-url.ts – builds tarball from URL"]:::compute
      utils["_utils"]:::compute
    end
    subgraph "Shared Libraries"
      core["packages/core"]:::lib
      edge["packages/edge-polyfill"]:::lib
    end
  end

  subgraph "Infrastructure & CI/CD"
    developer["Developer / CI\n(GitHub Actions)"]:::external
    tsconfig["tsconfig.base.json"]:::infra
    vercelcfg["vercel.json"]:::infra
    githubcfg[".github/"]:::infra
    husky[".husky/"]:::infra
  end

  subgraph "External Systems"
    GithubAPI["GitHub\n(Raw URLs & API)"]:::external
    npmClient["npm / yarn client"]:::external
  end

  developer -.->|push code| githubcfg
  developer -.->|git hooks| husky
  githubcfg -.->|deploy| vercelcfg

  npmClient -->|npm install gitpkg:owner/repo/path| pkg
  pkg -->|"calls core logic"| core
  pkgurl -->|"calls core logic"| core
  core -->|"fetch repo.tar.gz"| GithubAPI
  core -->|"stream tarball"| npmClient
  pkg -->|"uses edge polyfill"| edge
  pkgurl -->|"uses edge polyfill"| edge
  Website -->|"fetch live demo / ping"| ping
  Website -->|"fetch from URL demo"| pkgurl

  click Website "https://github.com/equalma/gitpkg/tree/main/website/"
  click ping "https://github.com/equalma/gitpkg/blob/main/api/ping.ts"
  click pkg "https://github.com/equalma/gitpkg/blob/main/api/pkg.ts"
  click pkgurl "https://github.com/equalma/gitpkg/blob/main/api/pkg-from-url.ts"
  click utils "https://github.com/equalma/gitpkg/tree/main/api/_utils/"
  click core "https://github.com/equalma/gitpkg/tree/main/packages/core/"
  click edge "https://github.com/equalma/gitpkg/tree/main/packages/edge-polyfill/"
  click tsconfig "https://github.com/equalma/gitpkg/blob/main/tsconfig.base.json"
  click vercelcfg "https://github.com/equalma/gitpkg/blob/main/vercel.json"
  click githubcfg "https://github.com/equalma/gitpkg/tree/main/.github/"
  click husky "https://github.com/equalma/gitpkg/tree/main/.husky/"

  classDef compute fill:#CCE5FF,stroke:#000,color:#000
  classDef lib fill:#D4EDDA,stroke:#000,color:#000
  classDef ui fill:#FFF3CD,stroke:#000,color:#000
  classDef external fill:#E2E3E5,stroke:#000,color:#000
  classDef infra fill:#F8D7DA,stroke:#000,color:#000
```
