# openfoodfacts/openfoodfacts-nodejs architecture

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

- Interactive diagram: https://gitdiagram.com/openfoodfacts/openfoodfacts-nodejs
- Repository: https://github.com/openfoodfacts/openfoodfacts-nodejs

## Overview

##### Project type and purpose
- This is a language-specific SDK (a client library) for the Open Food Facts REST API.
- Its primary purpose is to provide TypeScript/JavaScript bindings: typed request/response models, convenience methods for each endpoint, error handling, and utilities to interact with the OpenFoodFacts API without dealing with raw HTTP calls or manual type definitions.

##### File structure
- Top-level files and folders:
- package.json, tsconfig.json, build/test/config files – standard Node.js library setup
- src/ – all source modules
– main.ts (entry point)
– formbody.ts, error.ts, search.ts, prices.ts, folksonomy.ts, nutripatrol.ts, robotoff.ts – per-feature API wrappers
– consts.ts – configuration constants (e.g., base URL)
– schemas/ – OpenAPI-generated TypeScript types for validation and typing, including server v2 definitions
– taxonomy/ – helper API and type definitions for taxonomy endpoints
- tests/ – unit tests and mock data validating each module’s behavior
- Build tools: openapi-typescript code generation is invoked via `yarn api` and integrated into the build pipeline

##### README for additional insights
- Confirms OpenAPI-based code generation for bindings
- Shows simple usage: instantiate client, call getProduct()
- Mentions Yarn v4, build/test commands

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Components
    subgraph "Client Application" 
        ClientApp["Client Application"]:::runtime
    end

    subgraph "SDK Library"
        subgraph "Entry Point"
            OpenFoodFacts["OpenFoodFacts (Facade)"]:::sdk
        end
        subgraph "HTTP Layer Utilities"
            FormBody["Form Body Builder"]:::sdk
            ErrorUtil["Error Handling"]:::sdk
            Consts["Configuration Constants"]:::sdk
        end
        subgraph "API Wrappers"
            Search["Search Module"]:::sdk
            Prices["Prices Module"]:::sdk
            Folksonomy["Folksonomy Module"]:::sdk
            NutriPatrol["NutriPatrol Module"]:::sdk
            Robotoff["Robotoff Module"]:::sdk
            TaxonomyAPI["Taxonomy API Module"]:::sdk
        end
        subgraph "Schemas / Types"
            SearchModels["Search Models"]:::schema
            PricesModels["Prices Models"]:::schema
            FolksonomyModels["Folksonomy Models"]:::schema
            NutriPatrolModels["NutriPatrol Models"]:::schema
            RobotoffModels["Robotoff Models"]:::schema
            ServerV2["Server v2 Definitions"]:::schema
        end
        subgraph "Taxonomy Types"
            TaxonomyTypes["Taxonomy Types"]:::schema
        end
    end

    subgraph "External Service"
        API["Open Food Facts REST API"]:::external
    end

    subgraph "Build-Time Tools"
        CodeGen["OpenAPI-TypeScript Generator"]:::build
    end

    subgraph "Test Suite"
        TestSearch["search.spec.ts"]:::test
        TestPrices["prices.spec.ts"]:::test
        TestFolksonomy["folksonomy.spec.ts"]:::test
        TestNutriPatrol["nutripatrol.spec.ts"]:::test
        TestPlatforms["platforms.spec.ts"]:::test
        TestUtils["test-utils.ts"]:::test
    end

    %% Runtime Flows
    ClientApp -->|"import & invoke"| OpenFoodFacts
    OpenFoodFacts -->|"uses"| FormBody
    OpenFoodFacts -->|"uses"| ErrorUtil
    OpenFoodFacts -->|"reads"| Consts
    OpenFoodFacts -->|"delegates to"| Search
    OpenFoodFacts -->|"delegates to"| Prices
    OpenFoodFacts -->|"delegates to"| Folksonomy
    OpenFoodFacts -->|"delegates to"| NutriPatrol
    OpenFoodFacts -->|"delegates to"| Robotoff
    OpenFoodFacts -->|"delegates to"| TaxonomyAPI

    Search -->|"HTTP request"| API
    Prices -->|"HTTP request"| API
    Folksonomy -->|"HTTP request"| API
    NutriPatrol -->|"HTTP request"| API
    Robotoff -->|"HTTP request"| API
    TaxonomyAPI -->|"HTTP request"| API

    API -->|"JSON response"| Search
    API -->|"JSON response"| Prices
    API -->|"JSON response"| Folksonomy
    API -->|"JSON response"| NutriPatrol
    API -->|"JSON response"| Robotoff
    API -->|"JSON response"| TaxonomyAPI

    Search -->|"deserialize & validate"| SearchModels
    Prices -->|"deserialize & validate"| PricesModels
    Folksonomy -->|"deserialize & validate"| FolksonomyModels
    NutriPatrol -->|"deserialize & validate"| NutriPatrolModels
    Robotoff -->|"deserialize & validate"| RobotoffModels
    TaxonomyAPI -->|"deserialize & validate"| ServerV2
    TaxonomyAPI -->|"deserialize & validate"| TaxonomyTypes

    OpenFoodFacts -->|"returns typed object"| ClientApp

    %% Build-Time Flow
    CodeGen -.->|"generates"| SearchModels
    CodeGen -.->|"generates"| PricesModels
    CodeGen -.->|"generates"| FolksonomyModels
    CodeGen -.->|"generates"| NutriPatrolModels
    CodeGen -.->|"generates"| RobotoffModels
    CodeGen -.->|"generates"| ServerV2

    %% Testing Flow
    TestSearch -.->|"mocks & validates"| Search
    TestPrices -.->|"mocks & validates"| Prices
    TestFolksonomy -.->|"mocks & validates"| Folksonomy
    TestNutriPatrol -.->|"mocks & validates"| NutriPatrol
    TestPlatforms -.->|"mocks & validates"| OpenFoodFacts
    TestUtils -.->|"supports tests"| TestSearch

    %% Click Events
    click OpenFoodFacts "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/main.ts"
    click FormBody "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/formbody.ts"
    click ErrorUtil "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/error.ts"
    click Consts "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/consts.ts"
    click Search "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/search.ts"
    click Prices "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/prices.ts"
    click Folksonomy "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/folksonomy.ts"
    click NutriPatrol "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/nutripatrol.ts"
    click Robotoff "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/robotoff.ts"
    click TaxonomyAPI "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/taxonomy/api.ts"
    click SearchModels "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/schemas/search.ts"
    click PricesModels "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/schemas/prices.ts"
    click FolksonomyModels "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/schemas/folksonomy.ts"
    click NutriPatrolModels "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/schemas/nutripatrol.ts"
    click RobotoffModels "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/schemas/robotoff.ts"
    click ServerV2 "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/schemas/server/v2.ts"
    click TaxonomyTypes "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/src/taxonomy/types.ts"
    click TestSearch "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/tests/search.spec.ts"
    click TestPrices "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/tests/prices.spec.ts"
    click TestFolksonomy "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/tests/folksonomy.spec.ts"
    click TestNutriPatrol "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/tests/nutripatrol.spec.ts"
    click TestPlatforms "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/tests/platforms.spec.ts"
    click TestUtils "https://github.com/openfoodfacts/openfoodfacts-nodejs/blob/develop/tests/utils/test-utils.ts"

    %% Styles
    classDef runtime fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef sdk fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef schema fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef external fill:#eceff1,stroke:#546e7a,color:#37474f,stroke-dasharray: 5 5;
    classDef build fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c,stroke-dasharray: 5 5;
    classDef test fill:#e3f2fd,stroke:#1565c0,color:#0d47a1,stroke-dasharray: 2 2;
```
