# ismailummer/chefclaude architecture

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

- Interactive diagram: https://gitdiagram.com/ismailummer/chefclaude
- Repository: https://github.com/ismailummer/chefclaude

## Overview

##### Project type & purpose (from file tree + README)
This is a **single-page frontend application (SPA)** built with **React + Vite**. There is **no server-side/backend code** in the repository. The presence of:
- `ai.js`
- `components/ClaudeRecipe.jsx`
- `GEMINI.md`
- the README warning about limited API calls

…strongly indicates the app’s core purpose is **calling one or more external LLM APIs (e.g., Gemini and/or Claude) to generate or assist with recipes**, likely based on user-provided ingredients.

- **Browser/UI runtime**
- **React component tree**
- **AI integration module**
- **External AI APIs**
- **Build/runtime toolchain (Vite)**
- Possibly **static hosting** (since it’s a Vite SPA)

##### What the file structure implies architecturally
Top-level files:
- `index.html` → Vite entry HTML (bootstraps the SPA)
- `index.jsx` → React entry point (mounts app)
- `App.jsx` → root component/composition
- `index.css` → global styles
- `vite.config.js` → build/dev server configuration
- `package.json` / `package-lock.json` → dependencies, scripts (`npm start` likely mapped to `vite`)

Modules:
- `ai.js` → central integration layer for AI calls (treat as “service/client” module)
- `components/*` → UI components (presentation + some state/logic)

Other:
- `images/` → static assets

This suggests a typical React architecture:
- **Entry** → **Root component** → **Feature components**
- **Service module** for external API calls

##### UI updates (render recipe / handle errors / handle rate limits)

Error branches:
- API quota exceeded / 429
- network error
- invalid input

##### Runtime / Execution environment
- **User**
- **Browser**
- **React Runtime**
- **Vite Dev Server** (development-time)
- **Static Asset Hosting** (production-time; generic if unknown)

##### Application structure (inside SPA)
- **Entry point**
- `index.html`
- `index.jsx`
- **Root**
- `App.jsx`
- **Feature/UI components**
- `Main.jsx`
- `Header.jsx`
- `IngredientsList.jsx`
- `ClaudeRecipe.jsx`
- **AI integration**
- `ai.js` (API client / prompt builder / request handler)
- **Styling / assets**
- `index.css`
- `images/*`

##### External systems
- **LLM API provider(s)**
- Gemini API (supported/mentioned via `GEMINI.md`)
- Claude API (suggested via `ClaudeRecipe.jsx`)
- If only one is truly used, show one primary and the other as “optional/alternate provider”

##### UI + state flow
- `IngredientsList.jsx` → `Main.jsx` : “onAddIngredient(ingredient)”
- `Main.jsx` → `IngredientsList.jsx` : “props: ingredients[]”
- `Main.jsx` → `ClaudeRecipe.jsx` : “props: recipeText, isLoading, onGenerate()”
- `Main.jsx` → `ai.js` : “generateRecipe(ingredients)”
- `ai.js` → `External LLM API` : “HTTPS REST call (prompt → completion)”
- `External LLM API` → `ai.js` : “recipe text / structured response”
- `ai.js` → `Main.jsx` : “promise resolves/rejects”
- `Main.jsx` → `ClaudeRecipe.jsx` : “render recipe / render error”

- Developer → `npm install`
- Developer → `npm start` → Vite Dev Server
- Vite → serves `index.html` + bundles `index.jsx/App.jsx/components/*`

##### Component-based UI decomposition
- Presentational components vs stateful container component(s).
- “Main” is a likely state owner (container).

##### “Service module” pattern for external calls
`ai.js` should be shown as a distinct service boundary:
- Keeps API key handling, prompt construction, request/response parsing out of UI components.
- Makes it easy to swap LLM providers (Claude vs Gemini) — show as “Provider Adapter” if that matches `ai.js` behavior.

##### Frontend-only architecture
Be explicit: there is **no backend** here, so the browser is calling the AI API directly (unless a proxy is configured). If it is direct-from-browser, highlight:
- **API key exposure risk**
- **rate limiting/quota constraints**

##### Right: External APIs (Gemini/Claude)

User → IngredientsList → Main → ai.js → LLM API → ai.js → Main → ClaudeRecipe

This captures the essential runtime truth of this repo without inventing nonexistent backend services.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% C4-ish: Context + Container + Component (vertical layout)
  %% =========================================================

  %% -------------------------
  %% External Actors/Systems
  %% -------------------------
  U["User"]:::actor

  subgraph "External LLM Providers (3rd-party)"
    direction TB
    GEM["Gemini API"]:::external
    CLAUDE["Claude API"]:::external
    QUOTA["Note: Rate-limited / quota constrained\n(Direct-from-browser calls may expose API keys)"]:::note
    GEM --- QUOTA
    CLAUDE --- QUOTA
  end

  subgraph "Hosting & Delivery"
    direction TB
    HOST["Static Host (TBD)\n(e.g., Netlify/Vercel/S3)"]:::infra
    CDN["Static Assets\n(images, compiled JS/CSS)"]:::infra
    HOST -->|"serves"| CDN
  end

  %% -------------------------
  %% Client Runtime (Browser)
  %% -------------------------
  subgraph "Client Runtime (Browser)"
    direction TB

    B["Browser"]:::runtime

    subgraph "React SPA (Vite-built)"
      direction TB

      %% Entry / Bootstrap
      HTML["index.html\n(SPA Bootstrap)"]:::entry
      ENTRY["index.jsx\n(React Mount)"]:::entry
      CSS["index.css\n(Global Styles)"]:::cssStyle
      IMG["images/\n(Static Assets)"]:::asset

      %% App component tree
      APP["App.jsx\n(Root Component)"]:::ui

      subgraph "UI Components (components/)"
        direction TB
        MAIN["Main.jsx\n(State Owner / Page Container)"]:::ui
        HDR["Header.jsx\n(Branding)"]:::ui
        ING["IngredientsList.jsx\n(Input & List Mgmt)"]:::ui
        RECIPE["ClaudeRecipe.jsx\n(Recipe Output / Generate Trigger)"]:::ui
      end

      %% Service module
      AI["ai.js\n(AI Integration Service / API Client)"]:::service
    end
  end

  %% -------------------------
  %% Dev / Build Tooling
  %% -------------------------
  subgraph "Dev & Build Tooling (non-runtime)"
    direction TB
    DEV["Developer"]:::actor
    PKG["package.json\n(scripts & deps)"]:::tool
    LOCK["package-lock.json\n(lockfile)"]:::tool
    VITE["vite.config.js\n(Vite Dev Server / Build Config)"]:::tool
    IDX[".idx/\n(Google IDX config)"]:::tool
    README["README.md\n(Usage + API call warnings)"]:::doc
    GEMDOC["GEMINI.md\n(Gemini provider notes)"]:::doc
  end

  %% =========================================================
  %% Runtime Relationships (solid)
  %% =========================================================
  U -->|"uses"| B
  B -->|"loads"| HTML
  HTML -->|"bootstraps"| ENTRY
  ENTRY -->|"renders"| APP

  APP -->|"composes"| MAIN
  MAIN -->|"renders"| HDR
  MAIN -->|"props:ingredients[]"| ING
  ING -->|"onAddIngredient() / onRemove()"| MAIN

  MAIN -->|"props:recipeText,isLoading,onGenerate()"| RECIPE
  RECIPE -->|"onGenerate()"| MAIN

  MAIN -->|"function call: generateRecipe(ingredients)"| AI
  AI -->|"HTTPS REST call\n(prompt -> completion)"| GEM
  AI -->|"HTTPS REST call\n(prompt -> completion)"| CLAUDE
  GEM -->|"recipe response"| AI
  CLAUDE -->|"recipe response"| AI
  AI -->|"promise resolve/reject"| MAIN
  MAIN -->|"state update -> render"| RECIPE

  %% Assets/styles (runtime)
  CDN -->|"delivers"| IMG
  CDN -->|"delivers"| CSS
  CSS -->|"styles"| APP
  IMG -->|"referenced by"| APP

  %% =========================================================
  %% Build/Dev Relationships (dashed)
  %% =========================================================
  DEV -.->|"npm install"| PKG
  PKG -.->|"resolves"| LOCK
  DEV -.->|"npm start / vite"| VITE
  VITE -.->|"serves in dev"| HTML
  VITE -.->|"bundles"| ENTRY
  VITE -.->|"bundles"| APP
  VITE -.->|"bundles"| MAIN
  VITE -.->|"bundles"| AI
  VITE -.->|"outputs static build"| HOST

  README -.->|"documents"| DEV
  GEMDOC -.->|"documents"| DEV
  IDX -.->|"configures env"| DEV

  %% =========================================================
  %% Sequence Diagram (core flow) - kept vertical and separate
  %% =========================================================
  subgraph "Runtime Sequence: Generate Recipe"
    direction TB
    S0["1) User enters ingredients"]:::seq
    S1["2) IngredientsList updates Main state\n(via callbacks)"]:::seq
    S2["3) User clicks Generate"]:::seq
    S3["4) Main calls ai.js generateRecipe(ingredients)"]:::seq
    S4["5) ai.js calls LLM API (Gemini/Claude)"]:::seq
    S5["6) LLM returns recipe text (or error/429)"]:::seq
    S6["7) Main updates state\n(loading/result/error)"]:::seq
    S7["8) ClaudeRecipe renders recipe or error"]:::seq
    S0 --> S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7

    E1["Error path: 429 quota/rate limit\n-> show try later / disable generate"]:::note
    E2["Error path: network/invalid input\n-> render error state"]:::note
    S5 -->|"if 429"| E1
    S5 -->|"if error"| E2
  end

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click HTML "https://github.com/ismailummer/chefclaude/blob/main/index.html"
  click ENTRY "https://github.com/ismailummer/chefclaude/blob/main/index.jsx"
  click APP "https://github.com/ismailummer/chefclaude/blob/main/App.jsx"
  click MAIN "https://github.com/ismailummer/chefclaude/blob/main/components/Main.jsx"
  click HDR "https://github.com/ismailummer/chefclaude/blob/main/components/Header.jsx"
  click ING "https://github.com/ismailummer/chefclaude/blob/main/components/IngredientsList.jsx"
  click RECIPE "https://github.com/ismailummer/chefclaude/blob/main/components/ClaudeRecipe.jsx"
  click AI "https://github.com/ismailummer/chefclaude/blob/main/ai.js"
  click CSS "https://github.com/ismailummer/chefclaude/blob/main/index.css"
  click IMG "https://github.com/ismailummer/chefclaude/tree/main/images/"
  click VITE "https://github.com/ismailummer/chefclaude/blob/main/vite.config.js"
  click PKG "https://github.com/ismailummer/chefclaude/blob/main/package.json"
  click LOCK "https://github.com/ismailummer/chefclaude/blob/main/package-lock.json"
  click GEMDOC "https://github.com/ismailummer/chefclaude/blob/main/GEMINI.md"
  click README "https://github.com/ismailummer/chefclaude/blob/main/README.md"
  click IDX "https://github.com/ismailummer/chefclaude/tree/main/.idx/"

  %% =========================================================
  %% Styles (color is required)
  %% =========================================================
  classDef actor fill:#111827,stroke:#111827,color:#ffffff,stroke-width:1px
  classDef runtime fill:#0b1220,stroke:#334155,color:#e5e7eb,stroke-width:1px
  classDef entry fill:#2563eb,stroke:#1d4ed8,color:#ffffff,stroke-width:1px
  classDef ui fill:#1d4ed8,stroke:#1e40af,color:#ffffff,stroke-width:1px
  classDef service fill:#7c3aed,stroke:#5b21b6,color:#ffffff,stroke-width:1px
  classDef external fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1px
  classDef infra fill:#475569,stroke:#1f2937,color:#ffffff,stroke-width:1px
  classDef tool fill:#64748b,stroke:#334155,color:#ffffff,stroke-width:1px,stroke-dasharray: 4 3
  classDef doc fill:#0f766e,stroke:#115e59,color:#ffffff,stroke-width:1px,stroke-dasharray: 4 3
  classDef asset fill:#0369a1,stroke:#075985,color:#ffffff,stroke-width:1px
  classDef cssStyle fill:#0ea5e9,stroke:#0284c7,color:#ffffff,stroke-width:1px
  classDef note fill:#f59e0b,stroke:#b45309,color:#111827,stroke-width:1px
  classDef seq fill:#1f2937,stroke:#4b5563,color:#ffffff,stroke-width:1px
```
