# srinivas26k/ai-cookchef architecture

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

- Interactive diagram: https://gitdiagram.com/srinivas26k/ai-cookchef
- Repository: https://github.com/srinivas26k/ai-cookchef

## Overview

##### Project Type and Purpose
- BakeGenius AI is a full-stack web application combining a static multi-page frontend (HTML/CSS/JS) with a Node.js (Bun) backend.
- Purpose: let users log in/sign up, enter or speak vague recipe measurements, and get precise gram-based conversions via an AI-driven conversion engine.

##### Top-Level Components
a. Frontend (Presentation Layer)
- Static files (html/, css/, js/, favicon/, assets/) served to the browser
- Pages: index, about, convert, customize, login, signup, scale, recipe
- Modules:
– UI & styling (CSS files)
– Page logic (JS files invoking fetch/Gemini API)
– Voice-input handler (Web Speech API in js/)
– Firebase integration (firebase-config.js for hosting/auth/analytics)
b. Backend (Application Layer)
- Runtime: Bun (bun.lock) or Node.js (package.json)
- Entry point: server/server.js
- MVC sub-structure:
– Models: server/models/User.js
– Routes/Controllers: server/routes/auth.js (auth endpoints), plus conversion endpoints (implicit in server.js)
- Core responsibilities:
– User authentication & session management (signup/login, JWT or sessions)
– Conversion API:
· Receive measurement text
· Lookup ingredient densities (in-code DB or JSON)
· Call external Gemini API for NLP/contextual suggestions
· Compute grams and return JSON response
c. Database (Data Layer)
- MongoDB (URI in .env, .env.example) or another NoSQL store
- Collections: users, optionally conversion_history
d. External Services
- Gemini API (Google) for NLP and smart conversion suggestions
- Firebase Hosting/Analytics (optional)

##### Relationships & Data Flows
1. User opens a page (e.g., convert.html) → Browser fetches static assets from Firebase or static server.
2. User speaks or types ingredient measurement → Frontend JS module processes voice input or text.
3. Frontend sends POST /api/convert or GET /api/convert with payload → Backend server.js route.
4. Backend:
- Validates JWT/session (via auth.js)
- Queries density DB
- Calls Gemini API → Receives NLP payload
- Calculates precise grams → Responds to frontend.
5. Frontend receives JSON → Renders result + visualization (chart or table).
6. For login/signup: Frontend POST /api/auth/signup or /login → auth.js → User model → Database → JWT/session returned to frontend.

##### Architectural Patterns & Principles
- Layered Architecture: Presentation → Application → Data → External Services
- MVC on backend (Models, Controllers/Routes, Server as orchestrator)
- RESTful API design for conversion & auth endpoints
- Separation of concerns: static assets vs. dynamic API
- Client-side modular JS for voice, API calls, visualization

##### Summary
- Don’t over-complicate: separate into Frontend, Backend, DB, External.
- AI conversion flow (Frontend → Backend → Gemini API → Backend → Frontend).
- Auth flow separately.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client / Browser"
        direction TB
        Browser["User Browser"]:::frontend
        HTML_Pages["HTML Pages"]:::frontend
        CSS_Modules["CSS Styling Modules"]:::frontend
        JS_Modules["Page Logic & Voice-Input JS"]:::frontend
        Firebase_Config["Firebase Config"]:::frontend
        Assets["Static Assets"]:::frontend
        Favicon["Favicon & Manifest"]:::frontend
    end

    %% Static Hosting Layer
    subgraph "Static Assets Hosting (Firebase/CDN)"
        direction TB
        StaticServer["Static Server"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API Server"
        direction TB
        Server["Server Orchestrator (server.js)"]:::backend
        AuthRoute["Auth Route (auth.js)"]:::backend
        UserModel["User Model (User.js)"]:::backend
        BunLock["Runtime Lock (bun.lock)"]:::backend
        PackageJson["Package Manifests"]:::backend
        BackendGitignore["Backend .gitignore"]:::backend
        EnvExample["Env Config (.env.example)"]:::backend
    end

    %% Data & External Layer
    subgraph "Data & External Services"
        direction TB
        MongoDB["MongoDB"]:::database
        GeminiAPI["Gemini API"]:::external
    end

    %% Connections
    Browser -->|"HTTP GET static assets"| StaticServer
    StaticServer -->|Serves HTML/CSS/JS| Browser
    Browser -->|"POST /api/convert, /api/auth"| Server
    Server -->|"DB read/write"| MongoDB
    Server -->|"HTTPS GPT calls"| GeminiAPI
    Server -->|JWT/session validation| AuthRoute
    AuthRoute -->|"User CRUD"| MongoDB
    Server -->|"Calls AuthRoute"| AuthRoute
    Server -->|"Uses UserModel"| UserModel

    %% Click Events
    click HTML_Pages "https://github.com/srinivas26k/ai-cookchef/tree/main/html/"
    click CSS_Modules "https://github.com/srinivas26k/ai-cookchef/tree/main/css/"
    click JS_Modules "https://github.com/srinivas26k/ai-cookchef/tree/main/js/"
    click Firebase_Config "https://github.com/srinivas26k/ai-cookchef/blob/main/firebase-config.js"
    click Assets "https://github.com/srinivas26k/ai-cookchef/tree/main/assets/"
    click Favicon "https://github.com/srinivas26k/ai-cookchef/blob/main/favicon/site.webmanifest"
    click Server "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/server/server.js"
    click BunLock "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/server/bun.lock"
    click PackageJson "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/server/package.json"
    click UserModel "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/server/models/User.js"
    click AuthRoute "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/server/routes/auth.js"
    click BackendGitignore "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/.gitignore"
    click EnvExample "https://github.com/srinivas26k/ai-cookchef/blob/main/.env.example"
    click Documentation "https://github.com/srinivas26k/ai-cookchef/blob/main/README.md"
    click BackendDocs "https://github.com/srinivas26k/ai-cookchef/blob/main/backend/README.md"
    click Contributing "https://github.com/srinivas26k/ai-cookchef/blob/main/CONTRIBUTING.md"
    click CodeOfConduct "https://github.com/srinivas26k/ai-cookchef/blob/main/CODE_OF_CONDUCT.md"
    click RootGitignore "https://github.com/srinivas26k/ai-cookchef/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0066cc,color:#003366;
    classDef backend fill:#d4edda,stroke:#28a745,color:#155724;
    classDef database fill:#fff3cd,stroke:#ffcd39,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6f42c1,color:#381085;
    class Browser,StaticServer,HTML_Pages,CSS_Modules,JS_Modules,Firebase_Config,Assets,Favicon frontend
    class Server,AuthRoute,UserModel,BunLock,PackageJson,BackendGitignore,EnvExample backend
    class MongoDB database
    class GeminiAPI external

    %% Legend
    subgraph Legend
        direction LR
        L1["Frontend"]:::frontend
        L2["Backend"]:::backend
        L3["Database"]:::database
        L4["External Services"]:::external
    end
```
