# eyevinn/ad-normalizer architecture

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

- Interactive diagram: https://gitdiagram.com/eyevinn/ad-normalizer
- Repository: https://github.com/eyevinn/ad-normalizer

## Overview

##### Project Type & Purpose
- This project is a proxy service for an ad server. It normalizes ad creatives by transcoding and packaging VAST and VMAP documents. It is a full-stack backend service that interacts with external services (such as SVT Encore, a packaging service, MinIO storage, and Redis) to manage and deliver video ad assets.
- The README makes it clear that the service handles two endpoints (VAST and VMAP) and initiates media processing pipelines when necessary.

##### File Structure Insights
- The top-level JavaScript/TypeScript files (e.g., src/api.ts, src/server.ts) indicate that the service exposes HTTP endpoints.
- Several subdirectories (src/config, src/encore, src/minio, src/redis, src/util, src/vast, src/vmap) reveal a separation of concerns:
- "src/api.ts" and "src/server.ts" handle routing and entrypoints.
- "src/encore" contains code for interacting with the SVT Encore service.
- "src/minio" handles interactions with the MinIO storage system.
- "src/redis" manages redis client operations for caching and distributed locks.
- "src/vast" and "src/vmap" implement the logic for the two main endpoints.
- "src/util" likely provides logging and other utility functions.
- Configuration and build-related files (Dockerfile, tsconfig.json, GitHub workflows, etc.) indicate deployment aspects and project quality controls such as testing and linting.

##### Elements
- A labeled node for each major component including:
- “API Server (Ad Normalizer)” with sub-labels for VAST and VMAP endpoints.
- “Redis Cache & Distributed Lock”
- “SVT Encore Service (Transcoding Pipeline)”
- “MinIO Bucket (Asset Storage)”
- “Packaging Service / Callback Handler” (note the callback listener endpoint)
- “Ad Server / Client” as the consumer of the transformed assets.
- From client → API Server.
- API Server ↔ Redis (read/write).
- API Server → SVT Encore when a new job is initiated.
- SVT Encore → MinIO when asset processing and packaging are complete.
- API Server → Client with formatted response (JSON/XML).
- Connection with its purpose (e.g., “caches result”, “transcoding request”, “stores packaged asset”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Ad Server/Client"]:::external

    %% API Layer Subgraph
    subgraph "API Layer"
        API["API Server (Ad Normalizer)"]:::internal
        VAST["VAST Endpoint Logic"]:::internal
        VMAP["VMAP Endpoint Logic"]:::internal
        Utility["Utilities (Logging)"]:::internal
    end

    %% External and Service Components
    Redis["Redis Cache & Distributed Lock"]:::service
    Encore["SVT Encore Service (Transcoding Pipeline)"]:::service
    MinIO["MinIO Bucket (Asset Storage)"]:::service
    Callback["Callback Listener"]:::external

    %% Connections
    Client -->|"HTTP_request"| API
    API -->|"handles_VAST"| VAST
    API -->|"handles_VMAP"| VMAP
    API -->|"uses_logging"| Utility
    API -->|"cache_lookup"| Redis
    Redis -->|"return_cache"| API
    API -->|"initiate_transcoding"| Encore
    Encore -->|"stores_asset"| MinIO
    Encore -->|"triggers_callback"| Callback
    API -->|"returns_response"| Client

    %% Click Events
    click API "https://github.com/eyevinn/ad-normalizer/blob/main/src/api.ts"
    click VAST "https://github.com/eyevinn/ad-normalizer/blob/main/src/vast/vastApi.ts"
    click VMAP "https://github.com/eyevinn/ad-normalizer/blob/main/src/vmap/vmapApi.ts"
    click Encore "https://github.com/eyevinn/ad-normalizer/blob/main/src/encore/encoreclient.ts"
    click MinIO "https://github.com/eyevinn/ad-normalizer/blob/main/src/minio/minio.ts"
    click Redis "https://github.com/eyevinn/ad-normalizer/blob/main/src/redis/redisclient.ts"
    click Utility "https://github.com/eyevinn/ad-normalizer/blob/main/src/util/logger.ts"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef service fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
```
