# greywarden07/freshtrack architecture

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

- Interactive diagram: https://gitdiagram.com/greywarden07/freshtrack
- Repository: https://github.com/greywarden07/freshtrack

## Overview

##### Project type and purpose
- FreshTrack is a client-heavy single-page application (SPA) built with React.
- It leverages Firebase as a Backend-as-a-Service (BaaS) for Authentication, Firestore (database), and Storage.
- It also uses Tesseract.js (in-browser OCR) and an external AI service (Google Gemini) for recipe suggestions.

##### File structure
- Top-level: package.json / lock files, public/ (static assets), src/ (all React source).
- src/components/: UI components (Dashboard, FileUpload, HomePage, etc.).
- src/contexts/authContext/: React Context for Auth state and methods.
- src/services/: Plain-JS modules encapsulating calls to Firestore, Storage, OCR, notifications, recipes, mock data.
- src/firebase/: Firebase initialization and wrappers (auth.js, groceries.js, users.js, serviceSwitcher.js).

##### README for architectural insights
- Tech stack confirms React, Material UI, Framer Motion, React Router.
- Firebase is the sole backend.
- Receipt scanning is done client-side via Tesseract.js.
- Recipe suggestions can call Google Gemini AI via REST.

##### Main components & their relationships
a. Client (Browser) – hosts the React SPA.
b. React App
- UI Layer: src/components – renders pages, forms, dashboards.
- Context Layer: src/contexts/authContext – manages user session and injects Auth methods.
- Service Layer: src/services/*.js – encapsulates business logic and network calls.
- Firebase Layer: src/firebase/*.js – initializes Firebase SDKs and exposes wrappers.
- OCR Engine: Tesseract.js (runs in browser)
c. External Services
- Firebase Authentication
- Firebase Firestore (database)
- Firebase Storage (receipt images)
- Google Gemini AI API (recipe suggestions)

##### How data flows
- User action (e.g., “Upload Receipt”)
→ UI Component (FileUpload.js)
→ Service Layer (ocr.js → Tesseract.js for text extraction)
→ Service Layer (storage.js uploads original image to Firebase Storage)
→ Service Layer (expirySearch.js or groceries.js) writes parsed items + expiry dates to Firestore
→ Dashboard component subscribes (via Firestore onSnapshot) to display upcoming expiries
→ Recipe component calls recipe.js, which may call Google Gemini

##### Architectural patterns & design principles
- Separation of concerns: UI vs. context vs. services vs. external SDKs
- Single source of truth for auth via React Context
- Encapsulated data-access layer (services/*.js + firebase/*.js)
- Client-side rendering & processing (OCR)
- Event-driven UI updates via Firestore real-time subscriptions

##### Final advice
- Be thorough: separate each React layer and each external dependency.
- Don’t overcomplicate: focus on the 4 layers (UI, Context, Services, External) and their main interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Side (Browser)"
        Browser("User / Browser"):::user
        SPA["React SPA\n(React / Material UI / Framer Motion / React Router)"]:::frontend
    end

    Browser --> SPA

    subgraph "UI Layer"
        Dashboard["Dashboard.js"]:::frontend
        FileUpload["FileUpload.js"]:::frontend
        HomePage["HomePage.js"]:::frontend
        LoginPage["LoginPage.js"]:::frontend
        SignupPage["SignupPage.js"]:::frontend
        UploadPage["UploadPage.js"]:::frontend
        FirestoreBlockDetector["FirestoreBlockDetector.js"]:::frontend
        StorageDebug["StorageDebug.js"]:::frontend
    end

    SPA --> Dashboard
    SPA --> FileUpload
    SPA --> HomePage
    SPA --> LoginPage
    SPA --> SignupPage
    SPA --> UploadPage
    SPA --> FirestoreBlockDetector
    SPA --> StorageDebug

    subgraph "Context Layer"
        AuthContext["authContext\n(index.jsx)"]:::context
    end

    Dashboard --> AuthContext
    FileUpload --> AuthContext

    subgraph "Service Layer"
        OCRService["ocr.js\n(OCR Service)"]:::service
        StorageService["storage.js\n(Storage Service)"]:::service
        ExpirySearchService["expirySearch.js\n(Groceries Service)"]:::service
        NotificationService["notification.js\n(Notification Service)"]:::service
        RecipeService["recipe.js\n(Recipe Service)"]:::service
        MockDataService["mockDataService.js\n(Mock Data Service)"]:::service
    end

    FileUpload --> OCRService
    FileUpload --> StorageService
    OCRService --> StorageService
    StorageService --> ExpirySearchService
    ExpirySearchService --> NotificationService
    RecipeService --> NotificationService
    ExpirySearchService --> MockDataService

    subgraph "Firebase Layer"
        FirebaseInit["firebase.js\n(Firebase Init)"]:::firebase
        AuthSDK["auth.js\n(Firebase Auth)"]:::firebase
        FirestoreWrapper["groceries.js / users.js\n(Firestore)"]:::firebase
        StorageWrapper["serviceSwitcher.js\n(Service Switcher)"]:::firebase
    end

    AuthContext --> AuthSDK
    OCRService --> FirebaseInit
    StorageService --> StorageWrapper
    ExpirySearchService --> FirestoreWrapper
    MockDataService --> FirestoreWrapper

    subgraph "External Services"
        Tesseract["Tesseract.js\n(OCR Engine)"]:::external
        GoogleGemini["Google Gemini AI"]:::external
    end

    OCRService --> Tesseract
    RecipeService --> GoogleGemini
    FirestoreWrapper -.Realtime Subscription.-> Dashboard

    %% Click Events
    click Dashboard "https://github.com/greywarden07/freshtrack/blob/main/src/components/Dashboard.js"
    click FileUpload "https://github.com/greywarden07/freshtrack/blob/main/src/components/FileUpload.js"
    click HomePage "https://github.com/greywarden07/freshtrack/blob/main/src/components/HomePage.js"
    click LoginPage "https://github.com/greywarden07/freshtrack/blob/main/src/components/LoginPage.js"
    click SignupPage "https://github.com/greywarden07/freshtrack/blob/main/src/components/SignupPage.js"
    click UploadPage "https://github.com/greywarden07/freshtrack/blob/main/src/components/UploadPage.js"
    click FirestoreBlockDetector "https://github.com/greywarden07/freshtrack/blob/main/src/components/FirestoreBlockDetector.js"
    click StorageDebug "https://github.com/greywarden07/freshtrack/blob/main/src/components/StorageDebug.js"
    click AuthContext "https://github.com/greywarden07/freshtrack/blob/main/src/contexts/authContext/index.jsx"
    click OCRService "https://github.com/greywarden07/freshtrack/blob/main/src/services/ocr.js"
    click StorageService "https://github.com/greywarden07/freshtrack/blob/main/src/services/storage.js"
    click ExpirySearchService "https://github.com/greywarden07/freshtrack/blob/main/src/services/expirySearch.js"
    click NotificationService "https://github.com/greywarden07/freshtrack/blob/main/src/services/notification.js"
    click RecipeService "https://github.com/greywarden07/freshtrack/blob/main/src/services/recipe.js"
    click MockDataService "https://github.com/greywarden07/freshtrack/blob/main/src/services/mockDataService.js"
    click FirebaseInit "https://github.com/greywarden07/freshtrack/blob/main/src/firebase/firebase.js"
    click AuthSDK "https://github.com/greywarden07/freshtrack/blob/main/src/firebase/auth.js"
    click FirestoreWrapper "https://github.com/greywarden07/freshtrack/blob/main/src/firebase/groceries.js"
    click FirestoreWrapper "https://github.com/greywarden07/freshtrack/blob/main/src/firebase/users.js"
    click StorageWrapper "https://github.com/greywarden07/freshtrack/blob/main/src/firebase/serviceSwitcher.js"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef context fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20;
    classDef service fill:#fff3e0,stroke:#e65100,color:#e65100;
    classDef firebase fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a;
    classDef external fill:#ffebee,stroke:#b71c1c,color:#b71c1c;
    classDef user fill:#f1f8e9,stroke:#33691e,color:#33691e;
```
