# roth-sorayuth/foodlink architecture

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

- Interactive diagram: https://gitdiagram.com/roth-sorayuth/foodlink
- Repository: https://github.com/roth-sorayuth/foodlink

## Overview

Foodlink is a surplus-food rescue platform with separate customer and merchant web apps backed by an API and realtime gateway. Customers discover nearby listings, reserve food, and manage pickup orders; merchants manage listings and stores, fulfill orders, and view analytics. The graph preserves those distinct stages and notification/realtime capabilities. Source excerpts are partial, so some page-to-page and client-to-endpoint wiring is represented only where supported by the tree or documentation.

Main entry points: [`customer/src/App.jsx`](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/App.jsx) (Customer app shell), [`merchant/src/App.jsx`](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/App.jsx) (Merchant app shell), [`merchant/src/services/api.js`](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/services/api.js) (Merchant API client), [`server/src/routes/index.js`](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/index.js) (API route dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer app"]
  node_customer_app["Customer app shell<br/>[App.jsx]"]
  node_discover["Discover listings"]
  node_explore["Map exploration<br/>[ExploreView.jsx]"]
  node_bakery["Bakery details"]
  node_checkout["Checkout and claim"]
  node_pickup["Active pickup"]
  node_profile["Customer profile"]
  node_customer_session["Local session state<br/>[userSession.js]"]
  node_customer_api["Customer API client<br/>[api.js]"]
end

subgraph group_merchant["Merchant portal"]
  node_merchant_app["Merchant app shell<br/>[App.jsx]"]
  node_merchant_listings["Listing management"]
  node_create_listing["Create listing"]
  node_merchant_orders["Order fulfillment<br/>[MerchantOrders.jsx]"]
  node_pickup_verify["Pickup verification"]
  node_merchant_dashboard["Merchant dashboard"]
  node_analytics["Merchant analytics"]
  node_store_profile["Store profile"]
  node_merchant_api["Merchant API client<br/>[api.js]"]
  node_merchant_socket["Merchant realtime client<br/>[socket.js]"]
end

subgraph group_backend["API and realtime"]
  node_api_server["API server<br/>[index.js]"]
  node_api_routes["API route dispatch<br/>[index.js]"]
  node_listing_routes["Listing routes<br/>[listings.js]"]
  node_order_routes["Order routes<br/>[orders.js]"]
  node_store_routes["Store routes<br/>[stores.js]"]
  node_notification_routes["Notification routes<br/>[notifications.js]"]
  node_analytics_routes["Analytics routes<br/>[analytics.js]"]
  node_listing_controller["Listing operations"]
  node_order_controller["Order and pickup operations"]
  node_store_controller["Store operations"]
  node_notification_controller["Notification operations"]
  node_analytics_controller["Analytics operations"]
  node_realtime["Socket.IO gateway<br/>[index.js]"]
end

subgraph group_data["Persistent state"]
end

node_customer_actor(("Customer"))
node_merchant_actor(("Merchant"))

node_customer_actor -->|"uses"| node_customer_app
node_customer_app -->|"renders"| node_discover
node_customer_app -->|"renders"| node_explore
node_customer_app -->|"renders"| node_bakery
node_customer_app -->|"renders"| node_checkout
node_customer_app -->|"renders"| node_pickup
node_customer_app -->|"renders"| node_profile
node_customer_app -->|"saves cart and order"| node_customer_session
node_customer_app -->|"requests data"| node_customer_api
node_discover -->|"fetches listings"| node_customer_api
node_explore -->|"filters rescues"| node_discover
node_bakery -->|"loads store"| node_customer_api
node_checkout -->|"places order"| node_customer_api
node_pickup -->|"verifies pickup"| node_customer_api
node_merchant_actor -->|"uses"| node_merchant_app
node_merchant_app -->|"renders"| node_merchant_listings
node_merchant_app -->|"renders"| node_create_listing
node_merchant_app -->|"renders"| node_merchant_orders
node_merchant_app -->|"renders"| node_pickup_verify
node_merchant_app -->|"renders"| node_merchant_dashboard
node_merchant_app -->|"renders"| node_analytics
node_merchant_app -->|"renders"| node_store_profile
node_merchant_listings -->|"manages listings"| node_merchant_api
node_create_listing -->|"publishes listing"| node_merchant_api
node_merchant_orders -->|"loads orders"| node_merchant_api
node_pickup_verify -->|"verifies pickup"| node_merchant_api
node_merchant_dashboard -->|"loads dashboard"| node_merchant_api
node_analytics -->|"loads analytics"| node_merchant_api
node_store_profile -->|"updates store"| node_merchant_api
node_customer_api -->|"HTTP requests"| node_api_server
node_merchant_api -->|"HTTP requests"| node_api_server
node_api_server -->|"dispatches API"| node_api_routes
node_api_routes -->|"mounts routes"| node_listing_routes
node_api_routes -->|"mounts routes"| node_order_routes
node_api_routes -->|"mounts routes"| node_store_routes
node_api_routes -->|"mounts routes"| node_notification_routes
node_api_routes -->|"mounts routes"| node_analytics_routes
node_listing_routes -->|"dispatches"| node_listing_controller
node_order_routes -->|"dispatches"| node_order_controller
node_store_routes -->|"dispatches"| node_store_controller
node_notification_routes -->|"dispatches"| node_notification_controller
node_analytics_routes -->|"dispatches"| node_analytics_controller
node_api_server -->|"hosts sockets"| node_realtime
node_order_controller -->|"emits order events"| node_realtime
node_listing_controller -->|"emits listing events"| node_realtime
node_merchant_socket -.->|"connects"| node_realtime
node_listing_controller -->|"returns API response"| node_api_server
node_order_controller -->|"returns API response"| node_api_server

click node_customer_app "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/App.jsx"
click node_discover "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerExploreFeed.jsx"
click node_explore "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/ExploreView.jsx"
click node_bakery "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/BakeryDetailPage.jsx"
click node_checkout "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerCheckoutFlow.jsx"
click node_pickup "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerActivePickup.jsx"
click node_profile "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerProfile.jsx"
click node_customer_session "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/utils/userSession.js"
click node_customer_api "https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/services/api.js"
click node_merchant_app "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/App.jsx"
click node_merchant_listings "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Listings/MerchantListings.jsx"
click node_create_listing "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Listings/CreateListingPage.jsx"
click node_merchant_orders "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Orders/MerchantOrders.jsx"
click node_pickup_verify "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Orders/VerifyPickupPage.jsx"
click node_merchant_dashboard "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Dashboard/MerchantDashboard.jsx"
click node_analytics "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Analytics/MerchantAnalytics.jsx"
click node_store_profile "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/StoreProfile/MerchantProfile.jsx"
click node_merchant_api "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/services/api.js"
click node_merchant_socket "https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/services/socket.js"
click node_api_server "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/index.js"
click node_api_routes "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/index.js"
click node_listing_routes "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/listings.js"
click node_order_routes "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/orders.js"
click node_store_routes "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/stores.js"
click node_notification_routes "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/notifications.js"
click node_analytics_routes "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/analytics.js"
click node_listing_controller "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/listingsController.js"
click node_order_controller "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/ordersController.js"
click node_store_controller "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/storesController.js"
click node_notification_controller "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/notificationsController.js"
click node_analytics_controller "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/analyticsController.js"
click node_realtime "https://github.com/roth-sorayuth/foodlink/blob/main/server/src/index.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_customer_app,node_discover,node_explore,node_bakery,node_checkout,node_pickup,node_profile,node_customer_session,node_customer_api toneBlue
class node_merchant_app,node_merchant_listings,node_create_listing,node_merchant_orders,node_pickup_verify,node_merchant_dashboard,node_analytics,node_store_profile,node_merchant_api,node_merchant_socket toneAmber
class node_api_server,node_api_routes,node_listing_routes,node_order_routes,node_store_routes,node_notification_routes,node_analytics_routes,node_listing_controller,node_order_controller,node_store_controller,node_notification_controller,node_analytics_controller,node_realtime toneMint
class node_customer_actor,node_merchant_actor toneIndigo
```

## Components

### Customer app

- [Customer app shell](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/App.jsx): `customer/src/App.jsx`
- [Discover listings](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerExploreFeed.jsx): `customer/src/components/customer/CustomerExploreFeed.jsx`
- [Map exploration](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/ExploreView.jsx): `customer/src/components/customer/ExploreView.jsx`
- [Bakery details](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/BakeryDetailPage.jsx): `customer/src/components/customer/BakeryDetailPage.jsx`
- [Checkout and claim](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerCheckoutFlow.jsx): `customer/src/components/customer/CustomerCheckoutFlow.jsx`
- [Active pickup](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerActivePickup.jsx): `customer/src/components/customer/CustomerActivePickup.jsx`
- [Customer profile](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/components/customer/CustomerProfile.jsx): `customer/src/components/customer/CustomerProfile.jsx`
- [Local session state](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/utils/userSession.js): `customer/src/utils/userSession.js`
- [Customer API client](https://github.com/roth-sorayuth/foodlink/blob/main/customer/src/services/api.js): `customer/src/services/api.js`

### Merchant portal

- [Merchant app shell](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/App.jsx): `merchant/src/App.jsx`
- [Listing management](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Listings/MerchantListings.jsx): `merchant/src/pages/Listings/MerchantListings.jsx`
- [Create listing](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Listings/CreateListingPage.jsx): `merchant/src/pages/Listings/CreateListingPage.jsx`
- [Order fulfillment](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Orders/MerchantOrders.jsx): `merchant/src/pages/Orders/MerchantOrders.jsx`
- [Pickup verification](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Orders/VerifyPickupPage.jsx): `merchant/src/pages/Orders/VerifyPickupPage.jsx`
- [Merchant dashboard](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Dashboard/MerchantDashboard.jsx): `merchant/src/pages/Dashboard/MerchantDashboard.jsx`
- [Merchant analytics](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/Analytics/MerchantAnalytics.jsx): `merchant/src/pages/Analytics/MerchantAnalytics.jsx`
- [Store profile](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/pages/StoreProfile/MerchantProfile.jsx): `merchant/src/pages/StoreProfile/MerchantProfile.jsx`
- [Merchant API client](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/services/api.js): `merchant/src/services/api.js`
- [Merchant realtime client](https://github.com/roth-sorayuth/foodlink/blob/main/merchant/src/services/socket.js): `merchant/src/services/socket.js`

### API and realtime

- [API server](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/index.js): `server/src/index.js`
- [API route dispatch](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/index.js): `server/src/routes/index.js`
- [Listing routes](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/listings.js): `server/src/routes/listings.js`
- [Order routes](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/orders.js): `server/src/routes/orders.js`
- [Store routes](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/stores.js): `server/src/routes/stores.js`
- [Notification routes](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/notifications.js): `server/src/routes/notifications.js`
- [Analytics routes](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/routes/analytics.js): `server/src/routes/analytics.js`
- [Listing operations](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/listingsController.js): `server/src/controllers/listingsController.js`
- [Order and pickup operations](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/ordersController.js): `server/src/controllers/ordersController.js`
- [Store operations](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/storesController.js): `server/src/controllers/storesController.js`
- [Notification operations](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/notificationsController.js): `server/src/controllers/notificationsController.js`
- [Analytics operations](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/controllers/analyticsController.js): `server/src/controllers/analyticsController.js`
- [Socket.IO gateway](https://github.com/roth-sorayuth/foodlink/blob/main/server/src/index.js): `server/src/index.js`

### Other components

- **Customer**
- **Merchant**

## Connections

- Customer → Customer app shell: uses
- Customer app shell → Discover listings: renders
- Customer app shell → Map exploration: renders
- Customer app shell → Bakery details: renders
- Customer app shell → Checkout and claim: renders
- Customer app shell → Active pickup: renders
- Customer app shell → Customer profile: renders
- Customer app shell → Local session state: saves cart and order
- Customer app shell → Customer API client: requests data
- Discover listings → Customer API client: fetches listings
- Map exploration → Discover listings: filters rescues
- Bakery details → Customer API client: loads store
- Checkout and claim → Customer API client: places order
- Active pickup → Customer API client: verifies pickup
- Merchant → Merchant app shell: uses
- Merchant app shell → Listing management: renders
- Merchant app shell → Create listing: renders
- Merchant app shell → Order fulfillment: renders
- Merchant app shell → Pickup verification: renders
- Merchant app shell → Merchant dashboard: renders
- Merchant app shell → Merchant analytics: renders
- Merchant app shell → Store profile: renders
- Listing management → Merchant API client: manages listings
- Create listing → Merchant API client: publishes listing
- Order fulfillment → Merchant API client: loads orders
- Pickup verification → Merchant API client: verifies pickup
- Merchant dashboard → Merchant API client: loads dashboard
- Merchant analytics → Merchant API client: loads analytics
- Store profile → Merchant API client: updates store
- Customer API client → API server: HTTP requests
- Merchant API client → API server: HTTP requests
- API server → API route dispatch: dispatches API
- API route dispatch → Listing routes: mounts routes
- API route dispatch → Order routes: mounts routes
- API route dispatch → Store routes: mounts routes
- API route dispatch → Notification routes: mounts routes
- API route dispatch → Analytics routes: mounts routes
- Listing routes → Listing operations: dispatches
- Order routes → Order and pickup operations: dispatches
- Store routes → Store operations: dispatches
- Notification routes → Notification operations: dispatches
- Analytics routes → Analytics operations: dispatches
- API server → Socket.IO gateway: hosts sockets
- Order and pickup operations → Socket.IO gateway: emits order events
- Listing operations → Socket.IO gateway: emits listing events
- Merchant realtime client → Socket.IO gateway: connects
- Listing operations → API server: returns API response
- Order and pickup operations → API server: returns API response