# lonecruisader/ingredient-analyser architecture

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

- Interactive diagram: https://gitdiagram.com/lonecruisader/ingredient-analyser
- Repository: https://github.com/lonecruisader/ingredient-analyser

## Overview

##### Project type and purpose
- This is a full-stack web application called “Sephora Ingredient Analyzer.”
- Purpose: Let users search Sephora.com products, scrape ingredient lists, classify ingredients (natural vs. synthetic) using an LLM, calculate percentages and environmental impact, and display results in a responsive React UI.

##### File structure
- Top-level directories:
- frontend/ (React + TypeScript UI)
- backend/ (Express + TypeScript API + scraper + LLM integration)
- api/ (legacy or alternative JS endpoints)
- tasks/ and .cursor/ (documentation and rule files)
- frontend/src/components: UI building blocks (SearchBar, IngredientAnalysis)
- frontend/src/services/api.ts: HTTP client for backend calls
- backend/src/routes/search.ts: API endpoint for product search & analysis
- backend/src/services: cache.ts, llm.ts, scraper.ts — business logic modules
- backend/src/utils: classificationValidator, percentageCalculator, environmentalImpact, ingredientFormatter — helper functions
- Configuration and build files: tsconfig.json, ESLint, Prettier, Vite, Jest configs, Vercel deployment file.

##### README for additional insights
- Tech stack: React, Vite, Express, Axios, Cheerio, LLM integration, Jest, Supertest
- Key features described (search, breakdown, environmental impact)
- Development workflow (dev servers on ports, environment variables for backend).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Browser
    Browser["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        ReactApp["React App (UI)"]:::frontend
        SearchBar["SearchBar Component"]:::frontend
        IngredientAnalysis["IngredientAnalysis Component"]:::frontend
        APIClient["Frontend API Client (Axios)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        Server["Express API Server"]:::backend
        SearchRoute["Search Route (search.ts)"]:::backend
        subgraph "Services"
            direction TB
            Scraper["Cheerio Scraper Module"]:::backend
            LLMService["LLM Classification Service"]:::backend
            CacheService["Cache Layer Service"]:::datastore
        end
        subgraph "Utilities"
            direction TB
            Validator["Classification Validator"]:::util
            PercentageCalc["Percentage Calculator"]:::util
            EnvImpact["Environmental Impact"]:::util
            Formatter["Ingredient Formatter"]:::util
        end
    end

    %% Legacy API
    LegacyAPI["API Legacy Endpoints"]:::external

    %% External Services
    Sephora["Sephora.com (External)"]:::external
    ExternalLLM["External LLM API"]:::external

    %% CI/Test
    subgraph "CI/Test"
        direction TB
        FrontJest["frontend/jest.config.js"]:::test
        BackJest["backend/jest.config.js"]:::test
    end

    %% Data Flow
    Browser -->|"loads SPA"| ReactApp
    ReactApp -->|"renders"| SearchBar
    ReactApp -->|"renders"| IngredientAnalysis
    ReactApp -->|"calls API"| APIClient
    APIClient -->|"HTTP request"| Server
    Server -->|"routes to"| SearchRoute
    SearchRoute -->|"calls scraper"| Scraper
    Scraper -->|"fetch HTML"| Sephora
    SearchRoute -->|"calls LLM"| LLMService
    LLMService -->|"API call"| ExternalLLM
    SearchRoute -->|"reads/writes"| CacheService
    SearchRoute -->|"formats data"| Validator
    SearchRoute -->|"calculates percentages"| PercentageCalc
    SearchRoute -->|"assesses impact"| EnvImpact
    SearchRoute -->|"formats ingredients"| Formatter
    SearchRoute -->|"response JSON"| APIClient
    APIClient -->|"data to UI"| IngredientAnalysis
    Server -->|"legacy endpoints"| LegacyAPI

    %% Click Events
    click ReactApp "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/src/main.tsx"
    click ReactApp "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/src/App.tsx"
    click ReactApp "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/src/index.html"
    click SearchBar "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/src/components/SearchBar.tsx"
    click IngredientAnalysis "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/src/components/IngredientAnalysis.tsx"
    click APIClient "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/src/services/api.ts"
    click Server "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/server.ts"
    click SearchRoute "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/routes/search.ts"
    click Scraper "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/services/scraper.ts"
    click LLMService "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/services/llm.ts"
    click CacheService "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/services/cache.ts"
    click Validator "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/utils/classificationValidator.ts"
    click PercentageCalc "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/utils/percentageCalculator.ts"
    click EnvImpact "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/utils/environmentalImpact.ts"
    click Formatter "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/src/utils/ingredientFormatter.ts"
    click LegacyAPI "https://github.com/lonecruisader/ingredient-analyser/blob/main/api/index.ts"
    click LegacyAPI "https://github.com/lonecruisader/ingredient-analyser/blob/main/api/products.js"
    click FrontJest "https://github.com/lonecruisader/ingredient-analyser/blob/main/frontend/jest.config.js"
    click BackJest "https://github.com/lonecruisader/ingredient-analyser/blob/main/backend/jest.config.js"

    %% Styles
    classDef frontend fill:#E8F4FD,stroke:#0275d8,stroke-width:1px
    classDef backend fill:#E8F6E9,stroke:#5cb85c,stroke-width:1px
    classDef external fill:#F7F7F7,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5
    classDef datastore fill:#FFF5CC,stroke:#f0ad4e,stroke-width:1px
    classDef util fill:#FFEFE6,stroke:#d9534f,stroke-width:1px
    classDef test fill:#F2DEDE,stroke:#d2322d,stroke-width:1px
```
