# openfoodfacts/openfoodfacts-js architecture

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

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

## Overview

This is the Open Food Facts JavaScript/TypeScript SDK: callers create a client with a fetch implementation, invoke product or supporting service methods, and receive typed API responses. Its main workflow is routed through the OpenFoodFacts facade to Product Opener v2/v3, with separate query, Robotoff, and NutriPatrol clients. Other exported capabilities include search, folksonomy, prices, and knowledge panels. The graph reflects documented and indexed relationships; unsampled module internals are represented only where the tree and README support them.

Main entry points: [`src/off.ts`](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off.ts) (OpenFoodFacts client), [`src/schemas`](https://github.com/openfoodfacts/openfoodfacts-js/tree/develop/src/schemas) (OpenAPI schemas), [`src/robotoff.ts`](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/robotoff.ts) (Robotoff client), [`src/off-v2.ts`](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off-v2.ts) (Product Opener v2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client facade"]
  node_off["OpenFoodFacts client<br/>[off.ts]"]
end

subgraph group_product["Product API"]
  node_v2["Product Opener v2<br/>[off-v2.ts]"]
  node_v3["Product Opener v3<br/>[off-v3.ts]"]
  node_product_api(("Product Opener API"))
  node_taxonomy["Taxonomy API<br/>[api.ts]"]
end

subgraph group_services["Data services"]
  node_query["Facet query client<br/>[query.ts]"]
  node_query_service(("Query service"))
  node_search["Search client<br/>[search.ts]"]
  node_search_service(("Search service"))
  node_robotoff["Robotoff client<br/>[robotoff.ts]"]
  node_robotoff_service(("Robotoff service"))
  node_nutri["NutriPatrol client<br/>[nutripatrol.ts]"]
  node_nutri_service(("NutriPatrol service"))
  node_folksonomy["Folksonomy client<br/>[folksonomy.ts]"]
  node_folk_service(("Folksonomy service"))
  node_prices["Prices client<br/>[prices.ts]"]
  node_prices_service(("Prices service"))
  node_knowledge["Knowledge panels<br/>[knowledgepanels.ts]"]
end

subgraph group_internal["Types and schemas"]
  node_taxonomy_types["Taxonomy types<br/>[types.ts]"]
  node_schemas["OpenAPI schemas"]
  node_formbody["Form body encoding<br/>[formbody.ts]"]
end

node_caller(("SDK caller"))

node_caller -->|"creates client"| node_off
node_caller -->|"uses exported client"| node_search
node_off -->|"constructs"| node_v2
node_off -->|"constructs"| node_v3
node_off -->|"constructs"| node_robotoff
node_off -->|"constructs"| node_nutri
node_off -->|"constructs"| node_query
node_v2 -->|"sends API requests"| node_product_api
node_v3 -->|"sends API requests"| node_product_api
node_off -->|"fetches taxonomy"| node_taxonomy
node_query -->|"posts aggregates"| node_query_service
node_search -->|"sends endpoint requests"| node_search_service
node_robotoff -->|"sends endpoint requests"| node_robotoff_service
node_nutri -.->|"sends API requests"| node_nutri_service
node_folksonomy -.->|"sends API requests"| node_folk_service
node_prices -.->|"sends API requests"| node_prices_service
node_off -.->|"exposes panel methods"| node_knowledge
node_v2 -->|"uses v2 bindings"| node_schemas
node_v3 -->|"uses v3 bindings"| node_schemas
node_query -->|"uses query bindings"| node_schemas
node_search -->|"uses search bindings"| node_schemas
node_robotoff -->|"uses service bindings"| node_schemas
node_nutri -->|"uses service bindings"| node_schemas
node_folksonomy -->|"uses service bindings"| node_schemas
node_prices -->|"uses service bindings"| node_schemas
node_off -->|"uses taxonomy types"| node_taxonomy_types
node_robotoff -->|"serializes form body"| node_formbody

click node_off "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off.ts"
click node_v2 "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off-v2.ts"
click node_v3 "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off-v3.ts"
click node_taxonomy "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/taxonomy/api.ts"
click node_taxonomy_types "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/taxonomy/types.ts"
click node_query "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/query.ts"
click node_search "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/search.ts"
click node_robotoff "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/robotoff.ts"
click node_nutri "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/nutripatrol.ts"
click node_folksonomy "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/folksonomy.ts"
click node_prices "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/prices.ts"
click node_knowledge "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/knowledgepanels.ts"
click node_schemas "https://github.com/openfoodfacts/openfoodfacts-js/tree/develop/src/schemas"
click node_formbody "https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/formbody.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_off toneBlue
class node_v2,node_v3,node_product_api,node_taxonomy toneAmber
class node_query,node_query_service,node_search,node_search_service,node_robotoff,node_robotoff_service,node_nutri,node_nutri_service,node_folksonomy,node_folk_service,node_prices,node_prices_service,node_knowledge toneMint
class node_taxonomy_types,node_schemas,node_formbody toneRose
class node_caller toneIndigo
```

## Components

### Client facade

- [OpenFoodFacts client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off.ts): `src/off.ts`

### Product API

- [Product Opener v2](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off-v2.ts): `src/off-v2.ts`
- [Product Opener v3](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/off-v3.ts): `src/off-v3.ts`
- **Product Opener API**
- [Taxonomy API](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/taxonomy/api.ts): `src/taxonomy/api.ts`

### Data services

- [Facet query client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/query.ts): `src/query.ts`
- **Query service**
- [Search client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/search.ts): `src/search.ts`
- **Search service**
- [Robotoff client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/robotoff.ts): `src/robotoff.ts`
- **Robotoff service**
- [NutriPatrol client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/nutripatrol.ts): `src/nutripatrol.ts`
- **NutriPatrol service**
- [Folksonomy client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/folksonomy.ts): `src/folksonomy.ts`
- **Folksonomy service**
- [Prices client](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/prices.ts): `src/prices.ts`
- **Prices service**
- [Knowledge panels](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/knowledgepanels.ts): `src/knowledgepanels.ts`

### Types and schemas

- [Taxonomy types](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/taxonomy/types.ts): `src/taxonomy/types.ts`
- [OpenAPI schemas](https://github.com/openfoodfacts/openfoodfacts-js/tree/develop/src/schemas): `src/schemas`
- [Form body encoding](https://github.com/openfoodfacts/openfoodfacts-js/blob/develop/src/formbody.ts): `src/formbody.ts`

### Other components

- **SDK caller**

## Connections

- SDK caller → OpenFoodFacts client: creates client (evidence: `README.md`)
- SDK caller → Search client: uses exported client
- OpenFoodFacts client → Product Opener v2: constructs (evidence: `src/off.ts`)
- OpenFoodFacts client → Product Opener v3: constructs (evidence: `src/off.ts`)
- OpenFoodFacts client → Robotoff client: constructs (evidence: `src/off.ts`)
- OpenFoodFacts client → NutriPatrol client: constructs (evidence: `src/off.ts`)
- OpenFoodFacts client → Facet query client: constructs (evidence: `src/off.ts`)
- Product Opener v2 → Product Opener API: sends API requests (evidence: `src/off-v2.ts`)
- Product Opener v3 → Product Opener API: sends API requests (evidence: `src/off-v3.ts`)
- OpenFoodFacts client → Taxonomy API: fetches taxonomy (evidence: `src/off.ts`)
- Facet query client → Query service: posts aggregates (evidence: `src/query.ts`)
- Search client → Search service: sends endpoint requests (evidence: `src/search.ts`)
- Robotoff client → Robotoff service: sends endpoint requests (evidence: `src/robotoff.ts`)
- NutriPatrol client → NutriPatrol service: sends API requests
- Folksonomy client → Folksonomy service: sends API requests
- Prices client → Prices service: sends API requests
- OpenFoodFacts client → Knowledge panels: exposes panel methods
- Product Opener v2 → OpenAPI schemas: uses v2 bindings (evidence: `src/off-v2.ts`)
- Product Opener v3 → OpenAPI schemas: uses v3 bindings (evidence: `src/off-v3.ts`)
- Facet query client → OpenAPI schemas: uses query bindings (evidence: `src/query.ts`)
- Search client → OpenAPI schemas: uses search bindings (evidence: `src/search.ts`)
- Robotoff client → OpenAPI schemas: uses service bindings (evidence: `src/robotoff.ts`)
- NutriPatrol client → OpenAPI schemas: uses service bindings (evidence: `src/nutripatrol.ts`)
- Folksonomy client → OpenAPI schemas: uses service bindings (evidence: `src/folksonomy.ts`)
- Prices client → OpenAPI schemas: uses service bindings (evidence: `src/prices.ts`)
- OpenFoodFacts client → Taxonomy types: uses taxonomy types (evidence: `src/off.ts`)
- Robotoff client → Form body encoding: serializes form body (evidence: `src/robotoff.ts`)