# vtempest/grab-api architecture

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

- Interactive diagram: https://gitdiagram.com/vtempest/grab-api
- Repository: https://github.com/vtempest/grab-api

## Overview

##### Main Components
A. Source Code (src/)
- Core module: grab-api.ts
- CLI Entrypoints: grab-cli.js, grab-url-cli.js
B. Build & Bundling (root)
- TypeScript (tsconfig.json) → compile to ES/CJS
- Vite (vite.config.js) for docs/live-reload
- Bun/Node for installs (bun.lock, package.json)
C. Distribution (dist/)
D. Documentation Pipeline
- create-api-docs/ → custom script to pull JSDoc/TypeDoc into OpenAPI/MDX
- docs-config/ (Docusaurus config + plugin output)
- docs/ (generated static site)
E. CI/CD (/.github/workflows/docs.yml)
- On push: compile code, build docs, deploy to GH Pages, publish to npm
F. Consumers & Runtime
- Browser & Node apps import from npm
- Global “grab” API on window/global
- fetch() under the hood to call external REST APIs
- Optional: mock server, dev-tools overlay, caching, retry, pagination

##### Relationships & Data Flows
- Source Code → (TypeScript compiler + Vite) → dist artifacts → npm registry
- Source Code + create-api-docs → docs-config → Docusaurus build → static docs → GitHub Pages
- CI triggers both build pipelines and publishes outputs
- Runtime consumer (web or Node) pulls package from npm, calls grab() → fetch → external API → back to UI
- Mock server: grab.mock intercepts → returns synthetic response

##### Architectural Patterns & Design Principles
- Plugin/Strategy: Consumers supply retry, pagination, mock, caching strategies via options
- Doc-as-Code: Automated extraction of API types into MDX/OpenAPI templates
- Single-function façade: “grab()” entrypoint for all features
- CI-driven release: workflows automatically build, test, document, and publish

##### Key Technologies & Frameworks
- TypeScript + tsc → static types, .d.ts outputs
- Vite → local dev server for docs, pre-bundle
- Bun/Node → dependency manager, test runner
- Docusaurus → static site generator for docs
- GitHub Actions → CI/CD for tests, docs deploy, npm publish
- fetch API → native HTTP requests

##### Elements
- Source → Build → Dist → npm registry → Consumer
- Source + Docs Generator → Docusaurus → GitHub Pages
- Consumer → grab() → fetch → External API
- Blue for source/build pipelines
- Green for runtime (consumer + external API)
- Orange for docs pipeline
- Purple for CI/CD
- Annotations: file paths (e.g. src/grab-api.ts, create-api-docs/, docs-config/) and technologies (TypeScript, Docusaurus, GitHub Actions)

Summary:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI[".github/workflows/docs.yml"]:::ci
    end

    %% Source Code Layer
    subgraph "Source Code" 
        direction TB
        Core["grab() entrypoint\nsrc/grab-api.ts"]:::source
        Log["Logging Helper\nsrc/log.ts"]:::source
        Icons["Icons Helper\nsrc/icons/index.ts"]:::source
        Spinners["Spinner Definitions\nsrc/spinners.json"]:::source
        CLI1["CLI Entrypoint\nsrc/grab-cli.js"]:::source
        CLI2["CLI Entrypoint\nsrc/grab-url-cli.js"]:::source
    end

    %% Build & Bundling
    subgraph "Build & Bundling" 
        direction TB
        TSConfig["TypeScript Config\ntsconfig.json"]:::build
        ViteConfig["Vite Config\nvite.config.js"]:::build
        Lockfile["Dependency Lockfile\nbun.lock"]:::build
        PackageJSON["Package Manifest\npackage.json"]:::build
    end

    %% Distribution Artifacts
    subgraph "Distribution Artifacts" 
        direction TB
        Dist["dist/ (ES/CJS/Types/Icon Bundles)"]:::dist
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        DocsGen["Documentation Generator\ncreate-api-docs/"]:::docs
        DocsConfig["Docusaurus Config\ndocs-config/"]:::docs
        DocsSite["Generated Docs\ndocs/"]:::docs
    end

    %% Consumers & Runtime
    subgraph "Consumers & Runtime"
        direction TB
        Consumer["Browser/Node Consumer"]:::runtime
        MockServer["Optional Mock Server"]:::runtime
        GrabCall["grab()"]:::runtime
        Fetch["fetch()"]:::runtime
        ExternalAPI["External REST API"]:::runtime
    end

    %% GitHub Pages & npm registry
    GHPages["GitHub Pages"]:::docs
    NPM["npm Registry"]:::dist

    %% Connections
    CI -->|triggers build & docs| TSConfig
    CI -->|triggers build & docs| DocsGen
    CI -->|publishes| NPM

    Core --> TSConfig
    Log --> TSConfig
    Icons --> TSConfig
    Spinners --> TSConfig
    CLI1 --> TSConfig
    CLI2 --> TSConfig

    TSConfig --> Dist
    ViteConfig --> DocsSite
    PackageJSON --> Dist
    Lockfile --> Dist

    SourceCombined["Source Code"] -.->|feeds docs| DocsGen

    DocsGen --> DocsConfig
    DocsConfig --> DocsSite
    DocsSite --> GHPages

    Dist --> NPM
    NPM --> Consumer

    Consumer -->|calls| GrabCall
    GrabCall --> Fetch
    Fetch --> ExternalAPI
    GrabCall -->|intercepts| MockServer
    MockServer --> GrabCall

    %% Click Events
    click Core "https://github.com/vtempest/grab-api/blob/master/src/grab-api.ts"
    click Log "https://github.com/vtempest/grab-api/blob/master/src/log.ts"
    click Icons "https://github.com/vtempest/grab-api/blob/master/src/icons/index.ts"
    click Spinners "https://github.com/vtempest/grab-api/blob/master/src/spinners.json"
    click CLI1 "https://github.com/vtempest/grab-api/blob/master/src/grab-cli.js"
    click CLI2 "https://github.com/vtempest/grab-api/blob/master/src/grab-url-cli.js"
    click TSConfig "https://github.com/vtempest/grab-api/blob/master/tsconfig.json"
    click ViteConfig "https://github.com/vtempest/grab-api/blob/master/vite.config.js"
    click Lockfile "https://github.com/vtempest/grab-api/blob/master/bun.lock"
    click PackageJSON "https://github.com/vtempest/grab-api/blob/master/package.json"
    click Dist "https://github.com/vtempest/grab-api/tree/master/dist/"
    click DocsGen "https://github.com/vtempest/grab-api/tree/master/create-api-docs/"
    click DocsConfig "https://github.com/vtempest/grab-api/tree/master/docs-config/"
    click DocsSite "https://github.com/vtempest/grab-api/tree/master/docs/"
    click CI "https://github.com/vtempest/grab-api/blob/master/.github/workflows/docs.yml"
    classDef source fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef build fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef dist fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef docs fill:#FFF4D6,stroke:#F29D35,color:#F29D35
    classDef ci fill:#EAD7FF,stroke:#8E44AD,color:#8E44AD
    classDef runtime fill:#D6F5D6,stroke:#28A745,color:#28A745
```
