# vercel/og-image architecture

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

- Interactive diagram: https://gitdiagram.com/vercel/og-image
- Repository: https://github.com/vercel/og-image

## Overview

##### Project Type and Purpose
- The project is oriented toward dynamic OG image generation for social cards. It is a serverless application built primarily for Vercel deployments. Although the README warns that the repo is outdated (only working with Node.js 14), its architectural distinction still provides valuable insight.
- The README hints that newer projects should use @vercel/og, but for this legacy repo, it shows a structure characteristic of a service layer (API) that dynamically produces images.

##### File Structure
- Two main directories are clearly visible:
- The “api” directory: Contains the core logic for the image generation. Inside, apart from an "index.ts" (likely the entry point for the API requests), you have an "_lib" folder that organizes internal modules (chromium integration, options configuration, parsing, sanitization, templating, and type definitions). This indicates a clear separation of concerns within the backend.
- The “web” directory: Contains at least one file (archive.ts) suggesting a frontend route or additional web-based functionality.
- Additional directories/files:
- “public”: Contains static assets used by the front-end component (e.g., archive.html, style.css, robots.txt).
- Configuration files (package.json, tsconfig.json files in “api” and “web”, vercel.json, .yarnrc) provide hints about development and deployment processes.
- GitHub and contribution tools indicate open-source collaboration.

##### Key System Components
- API Component: Core service handling OG image generation:
- Entry point: api/index.ts
- Supporting libraries/modules: Located in api/_lib (such as template, parser, sanitizer, chromium integration).
- Assets: Fonts in api/_fonts (e.g., Inter-License.txt and Vera-License.txt), implicating the usage of specific typography in image generation.
- Web Component:
- Likely handling additional routes or administrative views (web/archive.ts) that integrate with the API.
- Public/Static Assets:
- Serve static HTML, CSS, and other files as required.
- External Services/Platforms:
- Vercel is used as the deployment platform (as indicated by vercel.json, .vercelignore, and the README mentioning Vercel support).

##### Relationships and Architectural Patterns
- The API server acts as the backend service that accepts requests, processes them using a set of modular libraries within the “api/_lib” directory, and produces an OG image as output.
- The web component likely interacts with or augments the API, offering archive or auxiliary functionality.
- Dependency and data flow:
- Incoming HTTP requests → routed to the API endpoint (api/index.ts) → internally use modules (parser, templating, etc.) for processing → font assets for image rendering → response returned.
- This design shows a clear separation of concerns, a modular file structure (for reusability and clarity), and a typical serverless design pattern when deployed on Vercel.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client (HTTP Request)"]:::client

    %% API Service Subgraph
    subgraph "Serverless API Service"
        direction TB
        API["API Endpoint"]:::api
        subgraph "Business Logic Modules"
            direction TB
            Parser["Parser Module"]:::module
            Sanitizer["Sanitizer Module"]:::module
            Template["Templating Module"]:::module
            Chromium["Chromium Integration"]:::module
            Options["Options Configuration"]:::module
        end
        Font["Font Assets"]:::font
    end

    %% Web Frontend Subgraph
    subgraph "Web Frontend"
        direction TB
        Archive["Archive Route"]:::web
    end

    %% Public/Static Assets
    StaticAssets["Static Assets (HTML, CSS, etc.)"]:::static

    %% Deployment Environment
    Vercel["Vercel Deployment Environment"]:::platform

    %% Data Flow
    Client -->|"HTTP_Request"| API
    API -->|"uses"| Parser
    API -->|"uses"| Sanitizer
    API -->|"uses"| Template
    API -->|"uses"| Chromium
    API -->|"uses"| Options
    API -->|"uses"| Font
    API -->|"sends_response"| Client

    Archive -->|"integrates_with"| API
    Archive -->|"serves"| StaticAssets

    API ---|"deployed_on"| Vercel
    Archive ---|"deployed_on"| Vercel
    StaticAssets ---|"hosted_on"| Vercel

    %% Click Events
    click API "https://github.com/vercel/og-image/blob/main/api/index.ts"
    click Parser "https://github.com/vercel/og-image/tree/main/api/_lib/"
    click Sanitizer "https://github.com/vercel/og-image/tree/main/api/_lib/"
    click Template "https://github.com/vercel/og-image/tree/main/api/_lib/"
    click Chromium "https://github.com/vercel/og-image/tree/main/api/_lib/"
    click Options "https://github.com/vercel/og-image/tree/main/api/_lib/"
    click Font "https://github.com/vercel/og-image/tree/main/api/_fonts/"
    click Archive "https://github.com/vercel/og-image/blob/main/web/archive.ts"
    click StaticAssets "https://github.com/vercel/og-image/tree/main/public/"
    click Vercel "https://github.com/vercel/og-image/blob/main/vercel.json"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef module fill:#aff,stroke:#333,stroke-width:1px;
    classDef font fill:#cfc,stroke:#333,stroke-width:2px;
    classDef web fill:#fcf,stroke:#333,stroke-width:2px;
    classDef static fill:#ff9,stroke:#333,stroke-width:2px;
    classDef platform fill:#9cf,stroke:#333,stroke-width:2px;
```
