# gitnasr/snapsaverunoffical architecture

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

- Interactive diagram: https://gitdiagram.com/gitnasr/snapsaverunoffical
- Repository: https://github.com/gitnasr/snapsaverunoffical

## Overview

##### Project type and purpose
- This is an open‑source Node.js utility library (package) named “snapsaver‑downloader.”
- Its sole responsibility is to fetch direct media URLs (images/videos) from Facebook, Instagram, TikTok posts by proxying requests through the SnapSave.app API.

##### File structure
- Top‑level TypeScript modules:
- Download.ts – core API client logic
- utils.ts – URL normalization, platform detection, thumbnail adjustments
- types.ts – response and media data interfaces
- index.ts – public entry point exporting the main SnapSaver function and utilities
- Config and support files:
- tsconfig.json, package.json – build/tooling definitions
- jest.config.js, jest.setup.js – testing setup
- README.md – user documentation

##### Key points from README
- Purpose: single function `SnapSaver(url: string): Promise<…>`
- Features: automatic platform detection, URL validation/normalization, multiple quality options
- Extensibility: exports utility functions (normalizeURL, detectPlatformFromURL, fixThumbnail) for advanced use
- External dependency: SnapSave.app API (third‑party service)

##### Main components
a. User Application
- Any Node.js script that imports and invokes the library.
b. Library Entry Point (index.ts)
- Exposes the `SnapSaver` function and utilities.
c. URL Processing Module (utils.ts)
- normalizeURL
- detectPlatformFromURL
- fixThumbnail
d. Download Module (Download.ts)
- Builds the request payload for SnapSave.app
- Chooses the correct endpoint based on platform
- Handles HTTP request/response
e. Type Definitions (types.ts)
- SnapSaveDownloaderResponse, SnapSaveDownloaderData, SnapSaveDownloaderMedia
f. External Service
- SnapSave.app API endpoints (Facebook/Instagram/TikTok proxy)

##### Relationships and data flow
1) User App calls → 2) index.ts `SnapSaver(url)` →
3) utils.normalizeURL & detectPlatformFromURL →
4) Download.ts constructs HTTP request →
5) HTTP client calls → 6) SnapSave.app API →
7) API returns JSON →
8) Download.ts parses into types defined in types.ts →
9) index.ts returns Promise< SnapSaveDownloaderResponse > →
10) User App consumes result.

##### Architectural patterns and design principles
- Modular layering: clearly separated URL utilities vs. HTTP client logic.
- Single responsibility per module (SRP).
- Promise‑based async I/O.
- TypeScript interfaces enforce schema correctness.
- Minimal external coupling (only one external HTTP dependency).

##### Technologies, frameworks, and libraries
- Node.js, TypeScript
- Axios or built‑in fetch (whichever is used in Download.ts)
- Jest for unit testing (jest.config.js, jest.setup.js)
- NPM packaging (package.json)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level user application
    UserApp["User Application"]:::user
    UserApp -->|"calls SnapSaver(url)"| Index

    %% Public API entry point
    Index["index.ts\n(SnapSaver & exports)"]:::public
    Index -->|"normalizeURL()"| Utils
    Index -->|"detectPlatformFromURL()"| Utils
    Index -->|"fixThumbnail()"| Utils
    Index -->|"invoke Download"| Download
    Download -->|"return data"| Index
    Index -->|"returns Promise<Response>"| UserApp

    subgraph "Library Internals"
        direction TB
        Utils["utils.ts\n(URL Processing)"]:::internal
        Download["Download.ts\n(HTTP Client)"]:::internal
        Types["types.ts\n(Interfaces)"]:::internal
        Utils -->|"normalized URL"| Download
        Download -->|"maps JSON to types"| Types
    end

    %% External service
    SnapSaveAPI["SnapSave.app API\n(Facebook/Instagram/TikTok)"]:::external
    Download -->|"POST /api/download"| SnapSaveAPI
    SnapSaveAPI -->|"JSON response"| Download

    %% Support files
    subgraph "Support & Config"
        direction TB
        JestConfig["jest.config.js"]:::support
        JestSetup["jest.setup.js"]:::support
        TsConfig["tsconfig.json"]:::support
        PackageJson["package.json"]:::support
        Readme["README.md"]:::support
    end

    %% Click Events
    click Index "https://github.com/gitnasr/snapsaverunoffical/blob/main/index.ts"
    click Utils "https://github.com/gitnasr/snapsaverunoffical/blob/main/utils.ts"
    click Download "https://github.com/gitnasr/snapsaverunoffical/blob/main/Download.ts"
    click Types "https://github.com/gitnasr/snapsaverunoffical/blob/main/types.ts"
    click JestConfig "https://github.com/gitnasr/snapsaverunoffical/blob/main/jest.config.js"
    click JestSetup "https://github.com/gitnasr/snapsaverunoffical/blob/main/jest.setup.js"
    click TsConfig "https://github.com/gitnasr/snapsaverunoffical/blob/main/tsconfig.json"
    click PackageJson "https://github.com/gitnasr/snapsaverunoffical/blob/main/package.json"
    click Readme "https://github.com/gitnasr/snapsaverunoffical/blob/main/README.md"

    %% Styles
    classDef user fill:#dddddd,stroke:#555,stroke-width:1px;
    classDef public fill:#ccffcc,stroke:#2d662d,stroke-width:1px;
    classDef internal fill:#cce5ff,stroke:#2a5298,stroke-width:1px;
    classDef external fill:#fff2cc,stroke:#997300,stroke-width:1px;
    classDef support fill:#f2f2f2,stroke:#999,stroke-width:1px;
```
