> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terces.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Model Guide

> How regulatory data is structured in the Food Additives platform

This page explains how regulatory data is organized in the Food Additives platform, helping you understand the relationships between ingredients, food categories, permission rules, and conditions.

## Core Entities

The platform is built around six core entities across two regulatory jurisdictions:

<CardGroup cols={2}>
  <Card title="Ingredients" icon="flask">
    306 food additives identified by INS number (Codex) and E-number (EU). Each ingredient has a name, functional class, and cross-jurisdiction regulatory profile.
  </Card>

  <Card title="Food Categories" icon="utensils">
    266 Codex + 132 EU food categories, each organized in a hierarchy. Cross-jurisdiction category mapping enables side-by-side comparison.
  </Card>

  <Card title="Permission Rules" icon="check">
    7,400+ rules across Codex (5,355) and EU (2,045). Each rule represents one ingredient permitted in one food category, with usage limits, permission status, and difficulty scoring.
  </Card>

  <Card title="Regulatory Conditions" icon="file-lines">
    834 Codex conditions + 97 EU footnote definitions. Conditions restrict scope, add exceptions, or define specific use cases. EU footnotes are resolved from numeric references to full regulatory text.
  </Card>

  <Card title="Allergen Risk" icon="triangle-exclamation">
    14 EU-recognized major allergens mapped to food additive ingredients. 440 allergen-risk-scored rules identifying which ingredient-category combinations carry allergen exposure.
  </Card>

  <Card title="Cross-Regulation" icon="scale-balanced">
    2,653 matched ingredient-category pairs compared across Codex and EU. Shows which jurisdiction is stricter and where regulatory gaps exist.
  </Card>
</CardGroup>

## Entity Relationships

```mermaid theme={null}
erDiagram
    INGREDIENT ||--o{ PERMISSION_RULE : "is permitted in"
    FOOD_CATEGORY ||--o{ PERMISSION_RULE : "permits"
    PERMISSION_RULE ||--o{ CONDITION : "has"
    PERMISSION_RULE ||--o{ CODEX_STANDARD : "references"
    INGREDIENT ||--o{ FUNCTIONAL_CLASS : "serves as"
    FOOD_CATEGORY ||--o{ PRODUCT_ARCHETYPE : "maps to"
    PRODUCT_ARCHETYPE }o--|| INDUSTRY_GROUP : "belongs to"

    INGREDIENT {
        string ins_number PK
        string name
        string functional_class
    }
    FOOD_CATEGORY {
        string category_code PK
        string category_name
        string parent_category
        int hierarchy_level
    }
    PERMISSION_RULE {
        string ingredient FK
        string food_category FK
        string permission_status
        string usage_limit
        float max_level_value
        int difficulty_score
    }
    CONDITION {
        string note_code PK
        string note_text
        string note_type
    }
    PRODUCT_ARCHETYPE {
        string archetype_name PK
        string industry_group
    }
```

## How Entities Connect

### Ingredient → Permission Rules

Each ingredient can be permitted in many food categories. The **Category Reach** metric counts how many categories an ingredient appears in. For example, Citric Acid (INS 330) is one of the most versatile — permitted in over 100 food categories.

### Food Category → Permission Rules

Each food category permits many ingredients. The **Formulation Flexibility** metric counts how many ingredients are available. Categories like "Chewing gum" are highly flexible (70+ ingredients), while "Infant formula" is tightly restricted.

### Permission Rule → Conditions

A single rule can have zero or many conditions attached. Conditions are regulatory notes from the Codex standard that qualify the permission — for example:

* **Scope restriction:** "Only in surface treatment"
* **Exception:** "Except for products intended for infants"
* **Basis:** "Subject to national legislation of the importing country"

Rules with 3+ conditions are flagged as requiring **expert review**.

### Food Category → Product Archetype → Industry Group

Food categories are mapped to 57 **product archetypes** (e.g., Bread, Ice Cream, Ketchup) across 10 **industry groups** (e.g., Bakery & Cereals, Dairy & Ice Cream). This mapping enables product-centric lookups: "What ingredients can I use for bread?"

## Condition Types

Regulatory conditions are classified into types based on their content:

| Type           | Count | What it means                                                  |
| -------------- | ----- | -------------------------------------------------------------- |
| **Scope**      | 235   | Restricts where or how the ingredient can be used              |
| **Exception**  | 231   | Carves out specific products or situations from the permission |
| **Exclusion**  | 185   | Explicitly excludes certain uses                               |
| **Condition**  | 117   | Sets additional requirements for the permission                |
| **Basis**      | 59    | References the legal or regulatory basis                       |
| **Carry-Over** | 1     | Relates to carry-over from other ingredients                   |

## Food Category Hierarchy

Codex food categories are organized in a tree structure with up to 4 levels:

```
01.0  Dairy products and analogues
  01.1  Fluid milk and milk products
    01.1.1  Fluid milk (plain)
      01.1.1.1  Fluid milk (unflavoured)
      01.1.1.2  Fluid milk (flavoured)
    01.1.2  Other fluid milk products
  01.2  Fermented and renneted milk products
    ...
```

The platform includes both **leaf** categories (most specific) and **parent** categories. Permission rules at a parent level may apply to all children, while specific leaf rules take precedence.