# amannegi/freshnest architecture

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

- Interactive diagram: https://gitdiagram.com/amannegi/freshnest
- Repository: https://github.com/amannegi/freshnest

## Overview

##### Project type and purpose
- FreshNest is a full-stack online marketplace connecting farmers and customers.
- It comprises three user-facing clients (Web via React/Tailwind, Mobile via Flutter, and an Admin panel), a Node.js/Express backend with MongoDB Atlas, plus auxiliary services (Firebase Storage for images, Geolocation API).

##### File structure
- Top level:
- backend/ – Node.js/Express server
- frontend/flutter/ – Mobile client (Flutter)
- frontend/react/ – Web client (React + TailwindCSS)
- docs/, .github/, images/ – CI/workflow docs and assets
- backend/src/: follows MVC-style separation
- models/ – Mongoose schemas (user, cart, comment, millet_item)
- routes/ – Express routers (auth, cart, list, admin, search, profile)
- startup/ – db connection (db.js), route registration (routes.js)
- utils/ – hashing, logging, response wrappers, Swagger integration
- frontend/: both Flutter and React clients use a mutated MVP pattern
- application/ – API calls + business logic
- presentation/ – UI components + styling
- Configuration: ESLint, Swagger AutoGen, VSCode launch configs, Vercel/Netlify deployment files

##### README for additional insights
- Describes MVP mutation: clear separation of “application” vs. “presentation” layers
- Lists tech stack: Flutter (mobile), React/Tailwind (web), Node/Express (backend), MongoDB Atlas (database)
- Mentions Swagger-generated API docs and Firebase Storage for image uploads
- Deployment: Web on Netlify, Backend on Adaptable.io

##### Main components
A. Clients
- Web Client (React + Tailwind)
- Mobile Client (Flutter)
- Admin Interface (could be a role in either client)
B. API Layer
- Express.js server
- Route modules (auth, cart, list, profile, admin, search)
C. Business & Data Layer
- Controllers/Services encapsulated in “application” folders (frontends) and in backend utils
- Models (MongoDB schemas)
D. Database
- MongoDB Atlas (hosted)
E. External Services
- Firebase Storage (image uploads)
- Geolocation API (mobile location)
- Swagger UI (auto-generated docs)

##### Relationships and data flows
- Clients → send HTTP(S) requests (REST) → Express routes
- Routes → invoke business logic and Mongoose models → read/write MongoDB
- For file uploads: route handlers → Firebase Storage SDK → store/retrieve images
- Mobile client utilizes device GPS → Geolocation API → passes location to backend
- Swagger UI exposes API docs via /swagger endpoint
- Admin role requests → same API endpoints but with elevated permissions

##### Architectural patterns & design principles
- Mutated MVP in frontends:
- Application layer: data fetching, state management (providers/managers)
- Presentation layer: UI widgets/pages
- Backend: MVC-style with separation of models, routes (controllers), and startup/config
- Separation of concerns, single responsibility, and layered architecture

##### Technologies & frameworks to annotate
- Backend: Node.js, Express.js, Mongoose, Swagger AutoGen
- Database: MongoDB Atlas
- Web: React 18, Vite, TailwindCSS, ESLint
- Mobile: Flutter 3.16.9, Dart, Firebase Storage, geolocator plugin
- Deployment: Netlify (web), Adaptable.io (backend), Vercel config in backend

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        ReactClient["Web Client<br/>(React + Tailwind)"]:::ui
        subgraph "React Client Layers"
            direction TB
            ReactApp["Application Layer"]:::ui
            ReactPres["Presentation Layer"]:::ui
        end
        FlutterClient["Mobile Client<br/>(Flutter)"]:::ui
        subgraph "Flutter Client Layers"
            direction TB
            FlutterApp["Application Layer"]:::ui
            FlutterPres["Presentation Layer"]:::ui
        end
        AdminModule["Admin Interface Module"]:::ui
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        ExpressServer["Express.js Server"]:::api
        subgraph "Route Modules"
            direction TB
            AuthRoute["Auth Route"]:::api
            CartRoute["Cart Route"]:::api
            ListRoute["List Route"]:::api
            ProfileRoute["Profile Route"]:::api
            SearchRoute["Search Route"]:::api
            AdminRoute["Admin Route"]:::api
        end
        subgraph "Startup Configuration"
            direction TB
            DBConfig["DB Connection"]:::api
            RouteConfig["Routes Registration"]:::api
        end
        subgraph "Utils & Swagger"
            direction TB
            HashUtil["Hash Util"]:::api
            Logger["Logger"]:::api
            RespUtil["Response Util"]:::api
            SwaggerUtil["Swagger Integration"]:::api
            SwaggerOutput["Swagger JSON"]:::api
        end
    end

    %% Data & External Services Layer
    subgraph "Data & External Services" 
        direction TB
        MongoDB["MongoDB Atlas"]:::db
        subgraph "Mongoose Models"
            direction TB
            UserModel["User Model"]:::db
            CartModel["Cart Model"]:::db
            CommentModel["Comment Model"]:::db
            MilletModel["Millet Item Model"]:::db
        end
        FirebaseStorage["Firebase Storage"]:::ext
        GeoService["Geolocation API"]:::ext
    end

    %% Flows
    ReactClient -->|REST JSON<br/>JWT Auth| ExpressServer
    FlutterClient -->|REST JSON<br/>JWT Auth| ExpressServer
    AdminModule -->|REST JSON<br/>JWT Auth| ExpressServer

    ExpressServer --> AuthRoute
    ExpressServer --> CartRoute
    ExpressServer --> ListRoute
    ExpressServer --> ProfileRoute
    ExpressServer --> SearchRoute
    ExpressServer --> AdminRoute

    AuthRoute -->|calls| HashUtil
    AuthRoute -->|logs| Logger
    AnyRoute((Any Route)) -->|uses| RespUtil

    AuthRoute --> UserModel
    CartRoute --> CartModel
    ListRoute --> MilletModel
    ProfileRoute --> UserModel
    SearchRoute --> MilletModel
    AdminRoute --> CommentModel

    DBConfig --> MongoDB
    RouteConfig --> ExpressServer

    SwaggerUtil --> SwaggerOutput
    ExpressServer --> SwaggerUtil

    %% External interactions
    AuthRoute -.->|upload images| FirebaseStorage
    FlutterApp -.->|get location| GeoService

    %% Click events
    click ReactClient "https://github.com/amannegi/freshnest/tree/main/frontend/react/"
    click ReactApp "https://github.com/amannegi/freshnest/tree/main/frontend/react/src/data"
    click ReactPres "https://github.com/amannegi/freshnest/tree/main/frontend/react/src/components"
    click FlutterClient "https://github.com/amannegi/freshnest/tree/main/frontend/flutter/lib/"
    click FlutterApp "https://github.com/amannegi/freshnest/tree/main/frontend/flutter/lib/core/*/application"
    click FlutterPres "https://github.com/amannegi/freshnest/tree/main/frontend/flutter/lib/core/*/presentation"
    click AdminModule "https://github.com/amannegi/freshnest/tree/main/frontend/flutter/lib/core/admin"
    click ExpressServer "https://github.com/amannegi/freshnest/blob/main/backend/index.js"
    click AuthRoute "https://github.com/amannegi/freshnest/blob/main/backend/src/routes/auth.js"
    click CartRoute "https://github.com/amannegi/freshnest/blob/main/backend/src/routes/cart.js"
    click ListRoute "https://github.com/amannegi/freshnest/blob/main/backend/src/routes/list.js"
    click ProfileRoute "https://github.com/amannegi/freshnest/blob/main/backend/src/routes/profile.js"
    click SearchRoute "https://github.com/amannegi/freshnest/blob/main/backend/src/routes/search.js"
    click AdminRoute "https://github.com/amannegi/freshnest/blob/main/backend/src/routes/admin.js"
    click DBConfig "https://github.com/amannegi/freshnest/blob/main/backend/src/startup/db.js"
    click RouteConfig "https://github.com/amannegi/freshnest/blob/main/backend/src/startup/routes.js"
    click UserModel "https://github.com/amannegi/freshnest/blob/main/backend/src/models/user.js"
    click CartModel "https://github.com/amannegi/freshnest/blob/main/backend/src/models/cart.js"
    click CommentModel "https://github.com/amannegi/freshnest/blob/main/backend/src/models/comment.js"
    click MilletModel "https://github.com/amannegi/freshnest/blob/main/backend/src/models/millet_item.js"
    click HashUtil "https://github.com/amannegi/freshnest/blob/main/backend/src/utils/hashUtil.js"
    click Logger "https://github.com/amannegi/freshnest/blob/main/backend/src/utils/logger.js"
    click RespUtil "https://github.com/amannegi/freshnest/blob/main/backend/src/utils/response.js"
    click SwaggerUtil "https://github.com/amannegi/freshnest/blob/main/backend/src/utils/swagger.js"
    click SwaggerOutput "https://github.com/amannegi/freshnest/blob/main/backend/src/swagger_output.json"
    click FirebaseStorage "https://github.com/amannegi/freshnest/blob/main/frontend/flutter/lib/utils/firebase_storage.dart"
    click GeoService "https://github.com/amannegi/freshnest/blob/main/frontend/flutter/lib/core/auth/application/location_service.dart"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#005A9C,color:#000;
    classDef api fill:#DFFFD0,stroke:#5A8F00,color:#000;
    classDef db fill:#FFEFD0,stroke:#CC8400,color:#000;
    classDef ext fill:#FFD0D0,stroke:#A80000,color:#000;
```
