# majimba/ai-calorie-estimator architecture

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

- Interactive diagram: https://gitdiagram.com/majimba/ai-calorie-estimator
- Repository: https://github.com/majimba/ai-calorie-estimator

## Overview

##### Project Type & Purpose
- This is a full-stack web application (built with Next.js 13’s App Router) that lets users upload or capture food images, sends them to AI (OpenAI GPT-4 Vision) for calorie estimation, and displays results in the browser.

##### File Structure Highlights
- src/app – Next.js app routes and API routes.
- app/page.tsx, layout.tsx – the main UI shell
- app/api/estimate-calories/route.ts – core backend endpoint
- other api/* routes – debug, direct-estimate, mobile-estimate, etc.
- src/components – React UI components (ImageUploader, CalorieEstimator, ResultDisplay).
- src/lib – wrappers and utilities for Cloudinary, OpenAI, config, error handling, image processing.
- Config files – next.config.js, tailwind.config.js, tsconfig.json, vercel.json for deployment.

##### README Insights
- Frontend: Next.js + React + Tailwind CSS + React Hook Form + Zod
- Backend: Next.js API Routes (serverless functions)
- Services: Cloudinary for image storage, OpenAI GPT-4 Vision for analysis
- No persistent database – flows are stateless serverless calls.

a. Frontend (Browser)
- React UI components → Form validation (React Hook Form + Zod) → HTTP POST to /api/estimate-calories
b. Next.js Serverless API Layer
- Route handler (estimate-calories)
- lib/cloudinary.ts → uploads image → returns secure URL
- lib/openai.ts → sends image URL to GPT-4 Vision → receives JSON with calories, items, confidence
- lib/image-utils.ts / lib/error.ts handle preprocessing & errors
c. External Services
- Cloudinary (Image storage & CDN)
- OpenAI API (Vision model)
d. Frontend Rendering
- Receives JSON → CalorieResult / ResultsDisplay components → update UI

##### Architectural Patterns & Principles
- Separation of concerns: UI vs business logic vs external-service code in src/lib
- Serverless functions for scalability and pay-per-use billing
- Stateless, request → response flow (no DB)
- Modular component design (atomic UI components)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Layer
    subgraph "Browser (Next.js React App)"
        direction TB
        Layout["Main Layout"]:::frontend
        HomePage["Home Page"]:::frontend
        subgraph "UI Components"
            direction TB
            ImageUploader["ImageUploader"]:::frontend
            CalorieEstimator["CalorieEstimator"]:::frontend
            ResultDisplay["ResultDisplay"]:::frontend
            CalorieResult["CalorieResult"]:::frontend
            ResultsDisplay["ResultsDisplay"]:::frontend
            TextInput["TextInput"]:::frontend
            Icons["Icons Collection"]:::frontend
        end
    end

    %% Vercel Deployment
    Vercel("Vercel Deployment"):::cloud

    %% API Layer on Serverless
    subgraph "Next.js Serverless API Layer" 
        direction TB
        EstRoute["API Route: /estimate-calories"]:::backend
        DebugRoute["API Route: /debug"]:::backend
        DirectRoute["API Route: /direct-estimate"]:::backend
        MobileRoute["API Route: /mobile-estimate"]:::backend
        IOStestRoute["API Route: /ios-test"]:::backend
        PublicDebugRoute["API Route: /public-debug"]:::backend
    end

    %% lib utilities
    subgraph "Utility Libraries (src/lib)"
        direction TB
        CloudinaryUtil["Cloudinary Wrapper"]:::util
        OpenAIUtil["OpenAI GPT-4 Vision Wrapper"]:::util
        ImageUtils["Image Processing Utilities"]:::util
        ErrorUtils["Error Handling Utilities"]:::util
        ConfigUtil["Config & Env Loader"]:::util
        APIHelper["Generic API Helper"]:::util
        DebugUtil["Debug Utilities"]:::util
        Types["Type Definitions"]:::util
    end

    %% Config files
    subgraph "Config Files"
        direction TB
        nextConfig["next.config.js"]:::config
        tailwindConfig["tailwind.config.js"]:::config
        tsConfig["tsconfig.json"]:::config
        vercelConfig["vercel.json"]:::config
    end

    %% External Services
    CloudinaryService((Cloudinary Service)):::external
    OpenAIService((OpenAI GPT-4 Vision)):::external

    %% Relationships
    Layout --> HomePage
    HomePage --> ImageUploader
    HomePage --> CalorieEstimator
    HomePage --> ResultDisplay
    ImageUploader -->|fills| TextInput
    CalorieEstimator -->|uses| TextInput
    CalorieEstimator -->|renders| CalorieResult
    ResultDisplay -->|renders| ResultsDisplay

    HomePage -->|POST base64 image HTTPS| EstRoute
    Vercel --> EstRoute

    EstRoute -->|upload image REST| CloudinaryUtil
    EstRoute -->|call vision REST| OpenAIUtil
    EstRoute -->|process image| ImageUtils
    EstRoute -->|handle errors| ErrorUtils
    EstRoute -->|load env| ConfigUtil
    EstRoute -->|helper calls| APIHelper
    EstRoute -->|debug| DebugUtil
    EstRoute -->|types| Types

    CloudinaryUtil -->|HTTPS| CloudinaryService
    OpenAIUtil -->|HTTPS| OpenAIService
    CloudinaryService -->|URL| EstRoute
    OpenAIService -->|JSON result| EstRoute

    EstRoute -->|JSON result HTTPS| ResultDisplay

    %% Additional routes
    DebugRoute -->|utility| DebugUtil
    DirectRoute -->|utility| DebugUtil
    MobileRoute -->|utility| DebugUtil
    IOStestRoute -->|utility| DebugUtil
    PublicDebugRoute -->|utility| DebugUtil

    %% Config relations
    nextConfig --> Vercel
    tailwindConfig --> HomePage
    tsConfig --> Layout
    vercelConfig --> Vercel

    %% Click Events
    click Layout "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/layout.tsx"
    click HomePage "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/page.tsx"
    click EstRoute "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/api/estimate-calories/route.ts"
    click DebugRoute "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/api/debug/route.ts"
    click DirectRoute "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/api/direct-estimate/route.ts"
    click MobileRoute "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/api/mobile-estimate/route.ts"
    click IOStestRoute "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/api/ios-test/route.ts"
    click PublicDebugRoute "https://github.com/majimba/ai-calorie-estimator/blob/main/src/app/api/public-debug/route.ts"
    click ImageUploader "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/ImageUploader.tsx"
    click CalorieEstimator "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/CalorieEstimator.tsx"
    click ResultDisplay "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/ResultDisplay.tsx"
    click CalorieResult "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/CalorieResult.tsx"
    click ResultsDisplay "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/ResultsDisplay.tsx"
    click TextInput "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/TextInput.tsx"
    click Icons "https://github.com/majimba/ai-calorie-estimator/blob/main/src/components/icons.tsx"
    click CloudinaryUtil "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/cloudinary.ts"
    click OpenAIUtil "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/openai.ts"
    click ImageUtils "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/image-utils.ts"
    click ErrorUtils "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/error.ts"
    click ConfigUtil "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/config.ts"
    click APIHelper "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/api.ts"
    click DebugUtil "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/debug.ts"
    click Types "https://github.com/majimba/ai-calorie-estimator/blob/main/src/lib/types.ts"
    click nextConfig "https://github.com/majimba/ai-calorie-estimator/blob/main/next.config.js"
    click tailwindConfig "https://github.com/majimba/ai-calorie-estimator/blob/main/tailwind.config.js"
    click tsConfig "https://github.com/majimba/ai-calorie-estimator/blob/main/tsconfig.json"
    click vercelConfig "https://github.com/majimba/ai-calorie-estimator/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#037fff,stroke-width:1px
    classDef backend fill:#E8F0FF,stroke:#0047B2,stroke-width:1px
    classDef util fill:#FFF5CC,stroke:#D4B106,stroke-width:1px
    classDef external fill:#DFFFD6,stroke:#32A852,stroke-width:1px
    classDef config fill:#EEEEEE,stroke:#666666,stroke-width:1px
    classDef cloud fill:#E0F7FF,stroke:#00A4CC,stroke-width:1px
```
