# pedguedes090/api-vip architecture

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

- Interactive diagram: https://gitdiagram.com/pedguedes090/api-vip
- Repository: https://github.com/pedguedes090/api-vip

## Overview

##### Project Type and Purpose
- This is a backend‐focused, full‐stack-ish Node.js microservice exposing a RESTful API to download and process social‐media videos.
- Its core purpose is to accept video URLs (Facebook, Instagram, Threads, TikTok), fetch media, generate thumbnails, store them briefly in a local filesystem, and serve download links.

##### File Structure
- Top‐level files:
- server.js – the Express application entrypoint
- index.html – a simple static UI or test‐page (served from public)
- package.json / package-lock.json – dependency management
- Directories:
- module/ – per‐platform downloader modules (facebook.js, instagram.js, threads.js, tiktok.js)
- downloads/ – temporary storage for raw videos and thumbnails (subfolders for each platform)
- No explicit “routes” directory: routes are defined in server.js.
- No database—storage is purely filesystem based.
- Configuration via environment variables (PORT).

##### Readme Insights
- Exposes endpoints under /api: /media-info, /download, /platforms, /validate-url.
- Automatic cleanup after 5 minutes.
- Error handling for invalid/unsupported URLs and filesystem failures.

##### Components
a. Main Components
1. API Gateway (Express server in server.js)
2. Platform Handler Modules (facebook.js, instagram.js, threads.js, tiktok.js)
3. Filesystem Storage (downloads/ directory)
4. Cleanup Scheduler (timer in server.js performing 5-minute purges)
5. Client (could be index.html or external API consumers)
6. External Services (social‐media platforms’ video hosting endpoints)
b. Relationships and Interactions
- Client → sends HTTP request → API Gateway
- API Gateway → invokes Platform Handler → calls External Service
- Platform Handler → writes video + thumbnail → Filesystem Storage
- API Gateway → responds with download URLs pointing to Filesystem
- Cleanup Scheduler → periodically deletes old files from Filesystem
c. Architectural Patterns / Principles
- Modular design: one handler per platform → plug-and-play extensibility
- Single Node.js process runs API + scheduler
- Stateless request handling; persistence in local FS only (ephemeral)
d. Key Technologies
- Node.js & Express
- Native fs module for file I/O
- cron or setInterval for cleanup
- npm modules for HTTP requests and media processing (e.g., axios, ffmpeg wrappers)

##### Essential Detail Checklist
- Four platform modules as separate components feeding into the same API layer.
- Ephemeral nature of the downloads directory and its 5-minute TTL.
- Error handling paths (e.g., invalid URL → error response).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Client<br/>(Browser/Test Page)"]:::client

    %% API Layer
    subgraph "API Layer"
        API["API Gateway<br/>(Express server)"]:::api
        Config["Environment Config<br/>(PORT, env vars)"]:::config
        Error["Error Handler"]:::error
    end

    %% Handlers
    subgraph "Platform Handler Modules" 
        FB["Facebook Module"]:::module
        IG["Instagram Module"]:::module
        TH["Threads Module"]:::module
        TT["TikTok Module"]:::module
    end

    %% External Services
    subgraph "External Social-Media Services"
        ESFB["Facebook Video API"]:::external
        ESIG["Instagram API"]:::external
        ESTH["Threads API"]:::external
        ESTT["TikTok API"]:::external
    end

    %% Storage
    subgraph "Filesystem Storage (downloads/)" 
        StorageRoot["downloads/"]:::storage
        FBFolder["facebook/"]:::storage
        IGFolder["instagram/"]:::storage
        THFolder["threads/"]:::storage
        TTFolder["tiktok/"]:::storage
    end

    %% Scheduler
    Scheduler{"Cleanup Scheduler<br/>(5-minute purge)"}:::scheduler

    %% Connections
    Client -->|"POST /download"| API
    Client -->|"GET /platforms, /media-info"| API
    API -->|"uses env vars"| Config
    API -->|"route request"| FB
    API -->|"route request"| IG
    API -->|"route request"| TH
    API -->|"route request"| TT
    API -->|onError| Error
    FB -->|"fetch video"| ESFB
    IG -->|"fetch video"| ESIG
    TH -->|"fetch video"| ESTH
    TT -->|"fetch video"| ESTT
    FB -->|"write video+thumb"| FBFolder
    IG -->|"write video+thumb"| IGFolder
    TH -->|"write video+thumb"| THFolder
    TT -->|"write video+thumb"| TTFolder
    FBFolder -->|through downloads/| StorageRoot
    IGFolder -->|through downloads/| StorageRoot
    THFolder -->|through downloads/| StorageRoot
    TTFolder -->|through downloads/| StorageRoot
    StorageRoot -->|"serve download link"| API
    API -->|"200 OK + link"| Client
    Scheduler -.->|"delete old files"| StorageRoot

    %% Click Events
    click API "https://github.com/pedguedes090/api-vip/blob/main/server.js"
    click FB "https://github.com/pedguedes090/api-vip/blob/main/module/facebook.js"
    click IG "https://github.com/pedguedes090/api-vip/blob/main/module/instagram.js"
    click TH "https://github.com/pedguedes090/api-vip/blob/main/module/threads.js"
    click TT "https://github.com/pedguedes090/api-vip/blob/main/module/tiktok.js"
    click StorageRoot "https://github.com/pedguedes090/api-vip/tree/main/downloads/"
    click FBFolder "https://github.com/pedguedes090/api-vip/tree/main/downloads/facebook/"
    click IGFolder "https://github.com/pedguedes090/api-vip/tree/main/downloads/instagram/"
    click THFolder "https://github.com/pedguedes090/api-vip/tree/main/downloads/threads/"
    click TTFolder "https://github.com/pedguedes090/api-vip/tree/main/downloads/tiktok/"
    click Client "https://github.com/pedguedes090/api-vip/blob/main/index.html"
    click Config "https://github.com/pedguedes090/api-vip/blob/main/package.json"
    click Error "https://github.com/pedguedes090/api-vip/blob/main/package-lock.json"
    click Scheduler "https://github.com/pedguedes090/api-vip/blob/main/server.js"
    click Client "https://github.com/pedguedes090/api-vip/blob/main/README.md"

    %% Styles
    classDef client fill:#f9d576,stroke:#d89c00,stroke-width:1px
    classDef api fill:#cce5ff,stroke:#3385ff,stroke-width:1px
    classDef module fill:#b3e6b3,stroke:#3d8b3d,stroke-width:1px
    classDef storage fill:#d6f5d6,stroke:#33cc33,stroke-width:1px
    classDef external fill:#ffe6cc,stroke:#ff9966,stroke-width:1px
    classDef scheduler stroke-dasharray: 5 5,fill:#fff2cc,stroke:#ffcc00,stroke-width:1px
    classDef config fill:#e6e6e6,stroke:#999999,stroke-width:1px
    classDef error fill:#f8d7da,stroke:#a71d2a,stroke-width:1px
```
