# heyimamit/gramify architecture

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

- Interactive diagram: https://gitdiagram.com/heyimamit/gramify
- Repository: https://github.com/heyimamit/gramify

## Overview

##### Project type and purpose
- Gramify is a full-stack, AI-powered web application for converting vague cooking measurements into precise grams and hosting a community forum.
- It combines a React single-page frontend, a Node.js/Express backend for routing, authentication, forum and media handling, a separate Python/FastAPI microservice for NLP/ML tasks, and a MongoDB Atlas database.

##### High-level components
a. Frontend (React + Context API + Tailwind/Vite)
b. Backend API (Node.js/Express + JWT auth + forum, image, voice controllers)
c. ML Microservice (Python/FastAPI handling NLP, fuzzy matching, density prediction, OCR, voice-to-text)
d. Database (MongoDB Atlas)
e. External Services (Gemini API for OCR, Google Web Speech API, Speech_recognition, any cloud hosting)

##### Relationships and interactions
- The React app issues HTTP(S) calls to the Node.js API endpoints (auth, forum, image, voice, conversion).
- Node.js routes incoming requests, applies middleware (requireAuth), interacts with MongoDB (via config/db.js) for users and posts, and proxies or orchestrates calls to the Python/FastAPI microservice for ingredient parsing, density prediction, fuzzy matching, OCR, and voice transcription.
- The Python microservice reads/writes any needed cache or supplementary data to MongoDB (via ml/database.py) and invokes third-party services (Gemini API, Google Web API).
- Static assets (index.html, JS, CSS, images) are served by the Node.js public folder.

##### Architectural patterns and design principles
- Separation of Concerns: UI, API layer, Machine Learning/AI logic, and data storage are decoupled.
- Microservice Pattern: NLP/ML engine is isolated in its own Python/FastAPI service.
- RESTful API: Node.js and Python services expose JSON endpoints with FastAPI TestClient coverage.
- Context API in React for global state (StoreContext.jsx)
- JWT Authentication middleware guards protected API routes.
- MVC-inspired organization in backend folder: models/controllers/routes.

##### Technologies, frameworks, libraries
- Frontend: React, Vite, Tailwind CSS, Context API, Hooks
- Backend: Node.js, Express, JWT, Mongoose (MongoDB driver)
- ML Service: Python 3.10, FastAPI, SpaCy, TextBlob, word2number, scikit-learn, Gemini API 2.5, Speech_recognition, Google Web API
- Database: MongoDB Atlas
- Testing: pytest, FastAPI TestClient
- Deployment: Google Cloud VM

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        Browser["User Browser"]:::external
        React["React SPA"]:::frontend
        Browser -->|"HTTP(S) Requests"| React
    end

    %% Backend Layer
    subgraph "Backend API (Node.js/Express)"
        direction TB
        API["Node.js/Express API"]:::backend
        AuthCtr["authController"]:::backend
        ForumCtr["forumController"]:::backend
        ImageCtr["imageController"]:::backend
        VoiceCtr["voiceController"]:::backend
        RequireAuth["requireAuth Middleware"]:::backend
        Server["server.js"]:::backend
        DBConfig["config/db.js"]:::backend
        Public["public (index.html & assets)"]:::backend
    end

    %% ML Microservice Layer
    subgraph "ML Microservice (FastAPI)"
        direction TB
        MLAPI["FastAPI Service"]:::ml
        AppPy["app.py"]:::ml
        ConfigPy["config.py"]:::ml
        MLDB["database.py"]:::ml
        Extraction["extraction.py"]:::ml
        ValidIng["valid_ing.py"]:::ml
        PredictCat["predict_category.py"]:::ml
        PredictDen["predict_missing_densities.py"]:::ml
        GeminiLoader["gemini_model_loader.py"]:::ml
        VoiceText["google_voice.py"]:::ml
        Cleanup["delete.py"]:::ml
    end

    %% Database
    subgraph "Database (MongoDB Atlas)"
        direction TB
        MongoDB[(MongoDB Atlas)]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GeminiAPI["Gemini OCR API"]:::ext
        GoogleSpeech["Google Web Speech API"]:::ext
    end

    %% Component Connections
    React -->|"REST API Calls"| API
    API -->|"JWT Validation"| RequireAuth
    API -->|"CRUD Operations"| MongoDB
    API -->|"Invoke ML Endpoints"| MLAPI
    MLAPI -->|"Cache/ReadWrite"| MongoDB
    MLAPI -->|"OCR Requests"| GeminiAPI
    MLAPI -->|"Voice-to-Text Requests"| GoogleSpeech
    API -->|"Serves SPA"| Public
    API -->|"Responses"| React

    %% Subcomponent Connections (Backend)
    API --> AuthCtr
    API --> ForumCtr
    API --> ImageCtr
    API --> VoiceCtr
    Server --> DBConfig
    Server --> RequireAuth

    %% Subcomponent Connections (ML)
    MLAPI --> AppPy
    MLAPI --> ConfigPy
    MLAPI --> MLDB
    MLAPI --> Extraction
    MLAPI --> ValidIng
    MLAPI --> PredictCat
    MLAPI --> PredictDen
    MLAPI --> GeminiLoader
    MLAPI --> VoiceText
    MLAPI --> Cleanup

    %% Click Events - Frontend
    click React "https://github.com/heyimamit/gramify/tree/main/frontend/"
    click Browser "https://github.com/heyimamit/gramify/blob/main/frontend/index.html"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/vite.config.js"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/main.jsx"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/App.jsx"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/context/StoreContext.jsx"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/pages/Converter/Converter.jsx"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/pages/Converter/Converter.css"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/pages/Forum/ForumPage.jsx"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/pages/Forum/ForumPage.css"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/index.css"
    click React "https://github.com/heyimamit/gramify/blob/main/frontend/src/tailwind.config.js"

    %% Click Events - Backend
    click API "https://github.com/heyimamit/gramify/tree/main/backend/"
    click Server "https://github.com/heyimamit/gramify/blob/main/backend/server.js"
    click DBConfig "https://github.com/heyimamit/gramify/blob/main/backend/config/db.js"
    click AuthCtr "https://github.com/heyimamit/gramify/blob/main/backend/controllers/authController.js"
    click ForumCtr "https://github.com/heyimamit/gramify/blob/main/backend/controllers/forumController.js"
    click ImageCtr "https://github.com/heyimamit/gramify/blob/main/backend/controllers/imageController.js"
    click VoiceCtr "https://github.com/heyimamit/gramify/blob/main/backend/controllers/voiceController.js"
    click RequireAuth "https://github.com/heyimamit/gramify/blob/main/backend/middlewares/requireAuth.js"
    click Public "https://github.com/heyimamit/gramify/blob/main/backend/public/index.html"

    %% Click Events - ML
    click MLAPI "https://github.com/heyimamit/gramify/tree/main/ml/"
    click AppPy "https://github.com/heyimamit/gramify/blob/main/ml/app.py"
    click ConfigPy "https://github.com/heyimamit/gramify/blob/main/ml/config.py"
    click MLDB "https://github.com/heyimamit/gramify/blob/main/ml/database.py"
    click Extraction "https://github.com/heyimamit/gramify/blob/main/ml/extraction.py"
    click ValidIng "https://github.com/heyimamit/gramify/blob/main/ml/valid_ing.py"
    click PredictCat "https://github.com/heyimamit/gramify/blob/main/ml/predict_category.py"
    click PredictDen "https://github.com/heyimamit/gramify/blob/main/ml/predict_missing_densities.py"
    click GeminiLoader "https://github.com/heyimamit/gramify/blob/main/ml/gemini_model_loader.py"
    click VoiceText "https://github.com/heyimamit/gramify/blob/main/ml/google_voice.py"
    click Cleanup "https://github.com/heyimamit/gramify/blob/main/ml/delete.py"

    %% Styles
    classDef frontend fill:#bbf,stroke:#000,color:#000
    classDef backend fill:#bfb,stroke:#000,color:#000
    classDef ml fill:#fdb,stroke:#000,color:#000
    classDef db fill:#def,stroke:#000,color:#000
    classDef ext fill:#ffd,stroke:#000,color:#000
    classDef external fill:#fff,stroke:#000,color:#000,stroke-dasharray: 5 5
```
