# eldrin23/surplus_backend architecture

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

- Interactive diagram: https://gitdiagram.com/eldrin23/surplus_backend
- Repository: https://github.com/eldrin23/surplus_backend

## Overview

Surpluz is a surplus-food marketplace API. Customers browse time-limited vendor listings, place orders, pay, and receive pickup details; vendors manage listings and orders, while admins oversee users, vendors, and transactions. The graph shows the HTTP entry point, route/controller responsibilities, authentication and upload layers, marketplace data models, and listing expiration. Route and controller links use the source index or shown excerpts; unsampled implementations are represented only where the index identifies their dependencies.

Main entry points: [`server.js`](https://github.com/eldrin23/surplus_backend/blob/main/server.js) (HTTP server), [`middleware/authMiddleware.js`](https://github.com/eldrin23/surplus_backend/blob/main/middleware/authMiddleware.js) (Token and role checks), [`models/FoodListing.js`](https://github.com/eldrin23/surplus_backend/blob/main/models/FoodListing.js) (Food listings), [`controllers/adminController.js`](https://github.com/eldrin23/surplus_backend/blob/main/controllers/adminController.js) (Marketplace administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routing"]
  node_server["HTTP server<br/>[server.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_listing_routes["Listing routes<br/>[listingRoutes.js]"]
  node_order_routes["Order routes<br/>[orderRoutes.js]"]
  node_vendor_routes["Vendor routes<br/>[vendorRoutes.js]"]
  node_admin_routes["Admin routes<br/>[adminRoutes.js]"]
  node_user_routes["User routes<br/>[userRoutes.js]"]
end

subgraph group_identity["Identity and access"]
  node_auth_controller["Registration and login<br/>[authController.js]"]
  node_auth_middleware["Token and role checks<br/>[authMiddleware.js]"]
  node_token["JWT generation<br/>[generateToken.js]"]
end

subgraph group_market["Marketplace workflows"]
  node_listing_controller["Listing management"]
  node_order_controller["Ordering and payment<br/>[orderController.js]"]
  node_vendor_controller["Vendor operations"]
  node_user_controller["User profile and activity<br/>[userController.js]"]
  node_admin_controller["Marketplace administration<br/>[adminController.js]"]
  node_scheduler["Listing expiration"]
end

subgraph group_data["Data and integrations"]
  node_upload["Image upload"]
  node_cloudinary_config["Cloudinary configuration<br/>[cloudinary.js]"]
  node_users[("User records<br/>[User.js]")]
  node_vendors[("Vendor records<br/>[Vendor.js]")]
  node_listings[("Food listings<br/>[FoodListing.js]")]
  node_orders[("Orders<br/>[Order.js]")]
  node_reviews[("Reviews<br/>[Review.js]")]
end

node_customer(("Customer"))
node_vendor_actor(("Vendor"))
node_admin_actor(("Administrator"))
node_mongodb[("MongoDB")]
node_razorpay["Razorpay"]
node_cloudinary["Cloudinary"]

node_customer -->|"sends requests"| node_server
node_vendor_actor -->|"sends requests"| node_server
node_admin_actor -->|"sends requests"| node_server
node_server -->|"mounts routes"| node_auth_routes
node_server -->|"mounts routes"| node_listing_routes
node_server -->|"mounts routes"| node_order_routes
node_server -->|"mounts routes"| node_vendor_routes
node_server -->|"mounts routes"| node_admin_routes
node_server -->|"mounts routes"| node_user_routes
node_auth_routes -->|"dispatches to"| node_auth_controller
node_listing_routes -->|"dispatches to"| node_listing_controller
node_order_routes -->|"dispatches to"| node_order_controller
node_vendor_routes -->|"dispatches to"| node_vendor_controller
node_admin_routes -->|"dispatches to"| node_admin_controller
node_user_routes -->|"dispatches to"| node_user_controller
node_listing_routes -->|"protects routes"| node_auth_middleware
node_order_routes -->|"protects routes"| node_auth_middleware
node_vendor_routes -->|"protects routes"| node_auth_middleware
node_admin_routes -->|"checks admin"| node_auth_middleware
node_user_routes -->|"protects routes"| node_auth_middleware
node_auth_controller -->|"creates and reads"| node_users
node_auth_controller -->|"creates and reads"| node_vendors
node_auth_controller -->|"generates tokens"| node_token
node_auth_middleware -->|"loads account"| node_users
node_auth_middleware -->|"loads account"| node_vendors
node_listing_controller -->|"reads and writes"| node_listings
node_listing_controller -->|"reads vendors"| node_vendors
node_listing_controller -->|"uses uploaded image"| node_upload
node_order_controller -->|"creates and reads"| node_orders
node_order_controller -->|"checks and updates stock"| node_listings
node_order_controller -.->|"creates payment order"| node_razorpay
node_vendor_controller -->|"manages vendors"| node_vendors
node_vendor_controller -->|"reads vendor orders"| node_orders
node_vendor_controller -->|"manages listings"| node_listings
node_user_controller -->|"manages profiles"| node_users
node_user_controller -->|"accesses listings"| node_listings
node_admin_controller -->|"administers vendors"| node_vendors
node_admin_controller -->|"administers users"| node_users
node_admin_controller -->|"reads listings"| node_listings
node_admin_controller -->|"reads transactions"| node_orders
node_server -->|"starts scheduler"| node_scheduler
node_scheduler -->|"expires listings"| node_listings
node_upload -->|"configures storage"| node_cloudinary_config
node_upload -->|"uploads images"| node_cloudinary
node_server -->|"connects to"| node_mongodb

click node_server "https://github.com/eldrin23/surplus_backend/blob/main/server.js"
click node_auth_routes "https://github.com/eldrin23/surplus_backend/blob/main/routes/authRoutes.js"
click node_listing_routes "https://github.com/eldrin23/surplus_backend/blob/main/routes/listingRoutes.js"
click node_order_routes "https://github.com/eldrin23/surplus_backend/blob/main/routes/orderRoutes.js"
click node_vendor_routes "https://github.com/eldrin23/surplus_backend/blob/main/routes/vendorRoutes.js"
click node_admin_routes "https://github.com/eldrin23/surplus_backend/blob/main/routes/adminRoutes.js"
click node_user_routes "https://github.com/eldrin23/surplus_backend/blob/main/routes/userRoutes.js"
click node_auth_controller "https://github.com/eldrin23/surplus_backend/blob/main/controllers/authController.js"
click node_auth_middleware "https://github.com/eldrin23/surplus_backend/blob/main/middleware/authMiddleware.js"
click node_token "https://github.com/eldrin23/surplus_backend/blob/main/utils/generateToken.js"
click node_listing_controller "https://github.com/eldrin23/surplus_backend/blob/main/controllers/listingController.js"
click node_order_controller "https://github.com/eldrin23/surplus_backend/blob/main/controllers/orderController.js"
click node_vendor_controller "https://github.com/eldrin23/surplus_backend/blob/main/controllers/vendorController.js"
click node_user_controller "https://github.com/eldrin23/surplus_backend/blob/main/controllers/userController.js"
click node_admin_controller "https://github.com/eldrin23/surplus_backend/blob/main/controllers/adminController.js"
click node_scheduler "https://github.com/eldrin23/surplus_backend/blob/main/utils/expirationScheduler.js"
click node_upload "https://github.com/eldrin23/surplus_backend/blob/main/middleware/uploadMiddleware.js"
click node_cloudinary_config "https://github.com/eldrin23/surplus_backend/blob/main/config/cloudinary.js"
click node_users "https://github.com/eldrin23/surplus_backend/blob/main/models/User.js"
click node_vendors "https://github.com/eldrin23/surplus_backend/blob/main/models/Vendor.js"
click node_listings "https://github.com/eldrin23/surplus_backend/blob/main/models/FoodListing.js"
click node_orders "https://github.com/eldrin23/surplus_backend/blob/main/models/Order.js"
click node_reviews "https://github.com/eldrin23/surplus_backend/blob/main/models/Review.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_auth_routes,node_listing_routes,node_order_routes,node_vendor_routes,node_admin_routes,node_user_routes toneBlue
class node_auth_controller,node_auth_middleware,node_token,node_mongodb toneAmber
class node_listing_controller,node_order_controller,node_vendor_controller,node_user_controller,node_admin_controller,node_scheduler toneMint
class node_upload,node_cloudinary_config,node_users,node_vendors,node_listings,node_orders,node_reviews toneRose
class node_customer,node_vendor_actor,node_admin_actor,node_razorpay,node_cloudinary toneIndigo
```

## Components

### API routing

- [HTTP server](https://github.com/eldrin23/surplus_backend/blob/main/server.js): `server.js`
- [Auth routes](https://github.com/eldrin23/surplus_backend/blob/main/routes/authRoutes.js): `routes/authRoutes.js`
- [Listing routes](https://github.com/eldrin23/surplus_backend/blob/main/routes/listingRoutes.js): `routes/listingRoutes.js`
- [Order routes](https://github.com/eldrin23/surplus_backend/blob/main/routes/orderRoutes.js): `routes/orderRoutes.js`
- [Vendor routes](https://github.com/eldrin23/surplus_backend/blob/main/routes/vendorRoutes.js): `routes/vendorRoutes.js`
- [Admin routes](https://github.com/eldrin23/surplus_backend/blob/main/routes/adminRoutes.js): `routes/adminRoutes.js`
- [User routes](https://github.com/eldrin23/surplus_backend/blob/main/routes/userRoutes.js): `routes/userRoutes.js`

### Identity and access

- [Registration and login](https://github.com/eldrin23/surplus_backend/blob/main/controllers/authController.js): `controllers/authController.js`
- [Token and role checks](https://github.com/eldrin23/surplus_backend/blob/main/middleware/authMiddleware.js): `middleware/authMiddleware.js`
- [JWT generation](https://github.com/eldrin23/surplus_backend/blob/main/utils/generateToken.js): `utils/generateToken.js`

### Marketplace workflows

- [Listing management](https://github.com/eldrin23/surplus_backend/blob/main/controllers/listingController.js): `controllers/listingController.js`
- [Ordering and payment](https://github.com/eldrin23/surplus_backend/blob/main/controllers/orderController.js): `controllers/orderController.js`
- [Vendor operations](https://github.com/eldrin23/surplus_backend/blob/main/controllers/vendorController.js): `controllers/vendorController.js`
- [User profile and activity](https://github.com/eldrin23/surplus_backend/blob/main/controllers/userController.js): `controllers/userController.js`
- [Marketplace administration](https://github.com/eldrin23/surplus_backend/blob/main/controllers/adminController.js): `controllers/adminController.js`
- [Listing expiration](https://github.com/eldrin23/surplus_backend/blob/main/utils/expirationScheduler.js): `utils/expirationScheduler.js`

### Data and integrations

- [Image upload](https://github.com/eldrin23/surplus_backend/blob/main/middleware/uploadMiddleware.js): `middleware/uploadMiddleware.js`
- [Cloudinary configuration](https://github.com/eldrin23/surplus_backend/blob/main/config/cloudinary.js): `config/cloudinary.js`
- [User records](https://github.com/eldrin23/surplus_backend/blob/main/models/User.js): `models/User.js`
- [Vendor records](https://github.com/eldrin23/surplus_backend/blob/main/models/Vendor.js): `models/Vendor.js`
- [Food listings](https://github.com/eldrin23/surplus_backend/blob/main/models/FoodListing.js): `models/FoodListing.js`
- [Orders](https://github.com/eldrin23/surplus_backend/blob/main/models/Order.js): `models/Order.js`
- [Reviews](https://github.com/eldrin23/surplus_backend/blob/main/models/Review.js): `models/Review.js`

### Other components

- **Customer**
- **Vendor**
- **Administrator**
- **MongoDB**
- **Razorpay**
- **Cloudinary**

## Connections

- Customer → HTTP server: sends requests
- Vendor → HTTP server: sends requests
- Administrator → HTTP server: sends requests
- HTTP server → Auth routes: mounts routes (evidence: `server.js`)
- HTTP server → Listing routes: mounts routes (evidence: `server.js`)
- HTTP server → Order routes: mounts routes (evidence: `server.js`)
- HTTP server → Vendor routes: mounts routes (evidence: `server.js`)
- HTTP server → Admin routes: mounts routes (evidence: `server.js`)
- HTTP server → User routes: mounts routes (evidence: `server.js`)
- Auth routes → Registration and login: dispatches to (evidence: `routes/authRoutes.js`)
- Listing routes → Listing management: dispatches to (evidence: `routes/listingRoutes.js`)
- Order routes → Ordering and payment: dispatches to (evidence: `routes/orderRoutes.js`)
- Vendor routes → Vendor operations: dispatches to (evidence: `routes/vendorRoutes.js`)
- Admin routes → Marketplace administration: dispatches to (evidence: `routes/adminRoutes.js`)
- User routes → User profile and activity: dispatches to (evidence: `routes/userRoutes.js`)
- Listing routes → Token and role checks: protects routes (evidence: `routes/listingRoutes.js`)
- Order routes → Token and role checks: protects routes (evidence: `routes/orderRoutes.js`)
- Vendor routes → Token and role checks: protects routes (evidence: `routes/vendorRoutes.js`)
- Admin routes → Token and role checks: checks admin (evidence: `routes/adminRoutes.js`)
- User routes → Token and role checks: protects routes (evidence: `routes/userRoutes.js`)
- Registration and login → User records: creates and reads (evidence: `controllers/authController.js`)
- Registration and login → Vendor records: creates and reads (evidence: `controllers/authController.js`)
- Registration and login → JWT generation: generates tokens (evidence: `controllers/authController.js`)
- Token and role checks → User records: loads account (evidence: `middleware/authMiddleware.js`)
- Token and role checks → Vendor records: loads account (evidence: `middleware/authMiddleware.js`)
- Listing management → Food listings: reads and writes (evidence: `controllers/listingController.js`)
- Listing management → Vendor records: reads vendors (evidence: `controllers/listingController.js`)
- Listing management → Image upload: uses uploaded image (evidence: `controllers/listingController.js`)
- Ordering and payment → Orders: creates and reads (evidence: `controllers/orderController.js`)
- Ordering and payment → Food listings: checks and updates stock (evidence: `controllers/orderController.js`)
- Ordering and payment → Razorpay: creates payment order (evidence: `controllers/orderController.js`)
- Vendor operations → Vendor records: manages vendors (evidence: `controllers/vendorController.js`)
- Vendor operations → Orders: reads vendor orders (evidence: `controllers/vendorController.js`)
- Vendor operations → Food listings: manages listings (evidence: `controllers/vendorController.js`)
- User profile and activity → User records: manages profiles (evidence: `controllers/userController.js`)
- User profile and activity → Food listings: accesses listings (evidence: `controllers/userController.js`)
- Marketplace administration → Vendor records: administers vendors (evidence: `controllers/adminController.js`)
- Marketplace administration → User records: administers users (evidence: `controllers/adminController.js`)
- Marketplace administration → Food listings: reads listings (evidence: `controllers/adminController.js`)
- Marketplace administration → Orders: reads transactions (evidence: `controllers/adminController.js`)
- HTTP server → Listing expiration: starts scheduler (evidence: `server.js`)
- Listing expiration → Food listings: expires listings (evidence: `utils/expirationScheduler.js`)
- Image upload → Cloudinary configuration: configures storage (evidence: `middleware/uploadMiddleware.js`)
- Image upload → Cloudinary: uploads images (evidence: `middleware/uploadMiddleware.js`)
- HTTP server → MongoDB: connects to (evidence: `server.js`)
