# tush1504/coupon-hunter architecture

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

- Interactive diagram: https://gitdiagram.com/tush1504/coupon-hunter
- Repository: https://github.com/tush1504/coupon-hunter

## Overview

1. **Overall shape**
   This is a single Next.js App Router application that combines the public UI, authenticated user flows, and backend API routes in one repo. The architecture is centered around Swiggy MCP-backed data retrieval, with PostgreSQL for durable app data, Redis for caching/coordination, and background workers for alert delivery.

2. **Public browsing surface**
   The main user-facing surfaces are the home page, the city/area deal listing pages, and per-deal detail pages. These are assembled from reusable sections like deal grids, hero content, and shared cards. The design goal is to let users compare restaurants and dishes by effective price, not just headline discount.

3. **Authenticated account surface**
   There is a separate dashboard and alerts page for signed-in users. These pages are likely where users manage saved alerts, see past favorites, and control notification preferences. The UI is split into presentational components and client-side data hooks, suggesting the dashboard is interactive rather than fully server-rendered.

4. **Auth boundary**
   Authentication is handled through dedicated API routes for login, callback, and logout, with PKCE support in `src/lib/auth/pkce.js` and session handling in `src/lib/auth/session.js`. This creates a clear boundary between anonymous browsing and user-scoped actions like alerts, shares, and address selection.

5. **Swiggy MCP integration layer**
   The `/api/mcp/*` routes are the core integration boundary to Swiggy’s MCP tools. They expose restaurant search, menu fetch, coupon lookup, cart simulation, order history, address handling, and menu search. The repo’s architecture makes these routes the canonical adapter between the app and Swiggy’s platform.

6. **Exact-price and cart simulation flow**
   The “exact price” feature uses a temporary cart workflow: add item, apply coupon, read the cart total, then flush/restores state. That means the app can calculate delivery, taxes, and coupon effects without permanently changing the user’s Swiggy cart. This is a key safety boundary: the app informs decisions but does not complete checkout or persist cart changes.

7. **Deals, coupons, and discovery model**
   Deal discovery is organized around restaurants, menu items, coupons, and effective price. Hooks like `useRestaurants`, `useCoupons`, `useMenu`, `useExactPrice`, and `useDishSearch` indicate a client data layer that consolidates MCP responses into ranked deal views. The UI components for savings, price display, tags, and badges reinforce that effective price is the primary ranking and display metric.

8. **Alerts subsystem**
   Alerts are a first-class product feature with CRUD API routes under `/api/alerts`, a dedicated alerts page, and a cron-triggered checker at `/api/cron/check-alerts`. The alert evaluation path likely queries the database for user thresholds, re-checks current deal conditions via MCP, and triggers notifications when conditions match.

9. **Background jobs and notifications**
   The repo includes workers in `workers/alertWorker.js` and `workers/smokeNotify.js`, plus notification adapters for email and Telegram. This suggests alert evaluation and message delivery are decoupled from the web request cycle, using queue-based background processing for reliability and delayed execution.

10. **Sharing subsystem**
   Deal sharing is modeled as its own resource with `/api/shares` and `/api/shares/[id]`. The README describes expiring share links with snapshot data, so this subsystem is likely responsible for creating immutable deal snapshots that can be revisited without re-running the full MCP lookup each time.

11. **Persistence and caching**
   PostgreSQL via Drizzle is the durable store for app-owned data such as alerts, shares, and user-linked preferences. Redis is used for caching Swiggy MCP responses and possibly for transient job coordination. This creates a clear split: persistent app state in Postgres, high-churn external data in Redis.

12. **Client-state and data-fetching layer**
   The front end uses TanStack Query for server-state fetching and caching, Zustand for local app state, and custom hooks to encapsulate domain logic. This keeps the component tree mostly declarative while pushing deal, alert, and address-fetching concerns into reusable data hooks.

13. **Component organization**
   Components are grouped by product function rather than by technical layer: cards, drawers, filters, sections, shared controls, and layout. That structure matches the app’s UX flows: browse deals, inspect details, configure exact price, and save/share/alert on interesting items.

14. **Deployment and operational boundaries**
   The project is configured for Vercel deployment, with app routes and cron-style execution paths fitting a serverless model. Tooling files for Tailwind, ESLint, Drizzle, and Next config indicate a standard modern Next stack, but the real architectural differentiators are the Swiggy MCP adapter, Redis caching, and the worker-driven notification pipeline.

Main entry points: [`src/app/api/alerts`](https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/alerts) (Alerts API), [`src/lib/db`](https://github.com/tush1504/coupon-hunter/tree/main/src/lib/db) (Database), [`src/app/deal/[id]/page.jsx`](https://github.com/tush1504/coupon-hunter/blob/main/src/app/deal/[id]/page.jsx) (Deal detail), [`src/app/api/cron/check-alerts/route.js`](https://github.com/tush1504/coupon-hunter/blob/main/src/app/api/cron/check-alerts/route.js) (Alert cron)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App surfaces"]
  node_home["Home<br/>page<br/>[page.js]"]
  node_deals_page["Area deals<br/>page<br/>[page.jsx]"]
  node_deal_page["Deal detail<br/>page<br/>[page.jsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[page.jsx]"]
  node_alerts_page["Alerts<br/>page<br/>[page.jsx]"]
  node_dashboard_client["Dashboard client"]
end

subgraph group_api["API layer"]
  node_mcp_routes[("MCP routes<br/>api adapter")]
  node_auth_routes[("Auth routes<br/>api adapter")]
  node_alerts_api[("Alerts API<br/>api resource")]
  node_shares_api[("Shares API<br/>api resource")]
  node_cron_check[("Alert cron<br/>cron endpoint<br/>[route.js]")]
end

subgraph group_client["Client state"]
  node_use_hooks["Data hooks"]
  node_app_store["App store<br/>zustand store<br/>[useAppStore.js]"]
end

subgraph group_backend["Backend services"]
  node_auth_core["Auth core<br/>auth lib"]
  node_mcp_client["MCP client<br/>integration"]
  node_db_core[("Database<br/>drizzle postgres")]
  node_redis[("Redis<br/>cache<br/>[redis.js]")]
  node_queue["Queue<br/>jobs<br/>[queue.js]"]
  node_workers["Workers<br/>background jobs"]
  node_notifications["Notifications<br/>delivery adapters"]
end

subgraph group_shared["Shared UI"]
  node_navbar["Navbar<br/>layout<br/>[Navbar.jsx]"]
  node_hero["Hero<br/>section<br/>[Hero.jsx]"]
  node_deal_grid["Deal grid<br/>section<br/>[DealGrid.jsx]"]
  node_public_deals["Public deals<br/>section<br/>[PublicDealGrid.jsx]"]
  node_alerts_list["Alerts list<br/>section<br/>[AlertsList.jsx]"]
  node_exact_price["Exact price<br/>drawer"]
  node_share_drawer["Share deal<br/>drawer"]
  node_alert_drawer["Alert setup<br/>drawer"]
end

node_home -->|"renders"| node_hero
node_home -->|"shows"| node_public_deals
node_deals_page -->|"renders"| node_deal_grid
node_deal_page -->|"opens"| node_exact_price
node_deal_page -->|"opens"| node_share_drawer
node_deal_page -->|"opens"| node_alert_drawer
node_dashboard_page -->|"hosts"| node_dashboard_client
node_dashboard_client -->|"composes"| node_alerts_list
node_dashboard_client -->|"uses"| node_app_store
node_navbar -->|"auth entry"| node_auth_routes
node_use_hooks -->|"fetches data"| node_mcp_routes
node_use_hooks -->|"reads writes"| node_alerts_api
node_use_hooks -->|"reads writes"| node_shares_api
node_use_hooks -->|"session state"| node_auth_routes
node_use_hooks -->|"syncs"| node_app_store
node_mcp_routes -->|"adapts"| node_mcp_client
node_auth_routes -->|"delegates"| node_auth_core
node_alerts_api -->|"persists"| node_db_core
node_shares_api -->|"persists"| node_db_core
node_cron_check -->|"loads rules"| node_db_core
node_cron_check -->|"rechecks deals"| node_mcp_client
node_cron_check -->|"enqueues"| node_queue
node_workers -->|"consumes"| node_queue
node_workers -->|"sends"| node_notifications
node_mcp_client -->|"caches"| node_redis
node_db_core -->|"augments"| node_redis
node_exact_price -->|"simulates cart"| node_mcp_routes
node_share_drawer -->|"creates share"| node_shares_api
node_alert_drawer -->|"creates alert"| node_alerts_api
node_alerts_list -->|"lists alerts"| node_alerts_api

click node_home "https://github.com/tush1504/coupon-hunter/blob/main/src/app/page.js"
click node_deals_page "https://github.com/tush1504/coupon-hunter/blob/main/src/app/deals/[city]/[area]/page.jsx"
click node_deal_page "https://github.com/tush1504/coupon-hunter/blob/main/src/app/deal/[id]/page.jsx"
click node_dashboard_page "https://github.com/tush1504/coupon-hunter/blob/main/src/app/dashboard/page.jsx"
click node_alerts_page "https://github.com/tush1504/coupon-hunter/blob/main/src/app/alerts/page.jsx"
click node_navbar "https://github.com/tush1504/coupon-hunter/blob/main/src/components/layout/Navbar.jsx"
click node_hero "https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/Hero.jsx"
click node_deal_grid "https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/DealGrid.jsx"
click node_public_deals "https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/PublicDealGrid.jsx"
click node_dashboard_client "https://github.com/tush1504/coupon-hunter/blob/main/src/app/dashboard/DashboardClient.jsx"
click node_alerts_list "https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/AlertsList.jsx"
click node_exact_price "https://github.com/tush1504/coupon-hunter/blob/main/src/components/drawers/ExactPriceDrawer.jsx"
click node_share_drawer "https://github.com/tush1504/coupon-hunter/blob/main/src/components/drawers/ShareDealDrawer.jsx"
click node_alert_drawer "https://github.com/tush1504/coupon-hunter/blob/main/src/components/drawers/DealAlertDrawer.jsx"
click node_app_store "https://github.com/tush1504/coupon-hunter/blob/main/src/store/useAppStore.js"
click node_mcp_routes "https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/mcp"
click node_auth_routes "https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/auth"
click node_alerts_api "https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/alerts"
click node_shares_api "https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/shares"
click node_cron_check "https://github.com/tush1504/coupon-hunter/blob/main/src/app/api/cron/check-alerts/route.js"
click node_auth_core "https://github.com/tush1504/coupon-hunter/tree/main/src/lib/auth"
click node_mcp_client "https://github.com/tush1504/coupon-hunter/tree/main/src/lib/mcp"
click node_db_core "https://github.com/tush1504/coupon-hunter/tree/main/src/lib/db"
click node_redis "https://github.com/tush1504/coupon-hunter/blob/main/src/lib/redis.js"
click node_queue "https://github.com/tush1504/coupon-hunter/blob/main/src/lib/queue.js"
click node_workers "https://github.com/tush1504/coupon-hunter/tree/main/workers"
click node_notifications "https://github.com/tush1504/coupon-hunter/tree/main/src/lib/notifications"

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_home,node_deals_page,node_deal_page,node_dashboard_page,node_alerts_page,node_dashboard_client toneBlue
class node_mcp_routes,node_auth_routes,node_alerts_api,node_shares_api,node_cron_check toneAmber
class node_use_hooks,node_app_store toneMint
class node_auth_core,node_mcp_client,node_db_core,node_redis,node_queue,node_workers,node_notifications toneRose
class node_navbar,node_hero,node_deal_grid,node_public_deals,node_alerts_list,node_exact_price,node_share_drawer,node_alert_drawer toneIndigo
```

## Components

### App surfaces

User-facing pages and shared UI composition.

- [Home](https://github.com/tush1504/coupon-hunter/blob/main/src/app/page.js): page · Public landing page for browsing deals. · `src/app/page.js`
- [Area deals](https://github.com/tush1504/coupon-hunter/blob/main/src/app/deals/[city]/[area]/page.jsx): page · City and area deal listing pages. · `src/app/deals/[city]/[area]/page.jsx`
- [Deal detail](https://github.com/tush1504/coupon-hunter/blob/main/src/app/deal/[id]/page.jsx): page · Per-deal detail view. · `src/app/deal/[id]/page.jsx`
- [Dashboard](https://github.com/tush1504/coupon-hunter/blob/main/src/app/dashboard/page.jsx): page · Signed-in user dashboard. · `src/app/dashboard/page.jsx`
- [Alerts](https://github.com/tush1504/coupon-hunter/blob/main/src/app/alerts/page.jsx): page · User alerts management page. · `src/app/alerts/page.jsx`
- [Dashboard client](https://github.com/tush1504/coupon-hunter/blob/main/src/app/dashboard/DashboardClient.jsx): client · Interactive dashboard composition. · `src/app/dashboard/DashboardClient.jsx`

### API layer

Route handlers that expose auth, deals, alerts, shares, and cron entrypoints.

- [MCP routes](https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/mcp): api adapter · Swiggy MCP boundary for restaurants, search, menu, coupons, cart, orders, and addresses. · `src/app/api/mcp`
- [Auth routes](https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/auth): api adapter · Login, callback, and logout endpoints. · `src/app/api/auth`
- [Alerts API](https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/alerts): api resource · CRUD for alert resources. · `src/app/api/alerts`
- [Shares API](https://github.com/tush1504/coupon-hunter/tree/main/src/app/api/shares): api resource · Create and fetch expiring deal shares. · `src/app/api/shares`
- [Alert cron](https://github.com/tush1504/coupon-hunter/blob/main/src/app/api/cron/check-alerts/route.js): cron endpoint · Scheduled alert evaluation entrypoint. · `src/app/api/cron/check-alerts/route.js`

### Client state

Hooks and local store used by interactive UI.

- **Data hooks**: hooks · Client data layer for restaurants, coupons, menus, prices, alerts, and filters.
- [App store](https://github.com/tush1504/coupon-hunter/blob/main/src/store/useAppStore.js): zustand store · Local UI state for cross-component interactions. · `src/store/useAppStore.js`

### Backend services

Core server-side integrations, persistence, caching, and jobs.

- [Auth core](https://github.com/tush1504/coupon-hunter/tree/main/src/lib/auth): auth lib · PKCE and session handling. · `src/lib/auth`
- [MCP client](https://github.com/tush1504/coupon-hunter/tree/main/src/lib/mcp): integration · Low-level client and food-specific MCP helpers. · `src/lib/mcp`
- [Database](https://github.com/tush1504/coupon-hunter/tree/main/src/lib/db): drizzle postgres · PostgreSQL schema and query layer for app-owned state. · `src/lib/db`
- [Redis](https://github.com/tush1504/coupon-hunter/blob/main/src/lib/redis.js): cache · Caching and transient coordination layer. · `src/lib/redis.js`
- [Queue](https://github.com/tush1504/coupon-hunter/blob/main/src/lib/queue.js): jobs · Background job coordination. · `src/lib/queue.js`
- [Workers](https://github.com/tush1504/coupon-hunter/tree/main/workers): background jobs · Alert delivery and smoke notification workers. · `workers`
- [Notifications](https://github.com/tush1504/coupon-hunter/tree/main/src/lib/notifications): delivery adapters · Email and Telegram delivery backends. · `src/lib/notifications`

### Shared UI

Reusable visual components and control elements.

- [Navbar](https://github.com/tush1504/coupon-hunter/blob/main/src/components/layout/Navbar.jsx): layout · Top-level navigation and auth entry. · `src/components/layout/Navbar.jsx`
- [Hero](https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/Hero.jsx): section · Landing page hero and value proposition. · `src/components/sections/Hero.jsx`
- [Deal grid](https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/DealGrid.jsx): section · Primary deal listing layout. · `src/components/sections/DealGrid.jsx`
- [Public deals](https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/PublicDealGrid.jsx): section · Browse-focused deal grid for anonymous users. · `src/components/sections/PublicDealGrid.jsx`
- [Alerts list](https://github.com/tush1504/coupon-hunter/blob/main/src/components/sections/AlertsList.jsx): section · Rendered alert rows and status. · `src/components/sections/AlertsList.jsx`
- [Exact price](https://github.com/tush1504/coupon-hunter/blob/main/src/components/drawers/ExactPriceDrawer.jsx): drawer · Temporary cart-based price simulation UI. · `src/components/drawers/ExactPriceDrawer.jsx`
- [Share deal](https://github.com/tush1504/coupon-hunter/blob/main/src/components/drawers/ShareDealDrawer.jsx): drawer · UI for creating share snapshots. · `src/components/drawers/ShareDealDrawer.jsx`
- [Alert setup](https://github.com/tush1504/coupon-hunter/blob/main/src/components/drawers/DealAlertDrawer.jsx): drawer · UI for creating or editing alert rules. · `src/components/drawers/DealAlertDrawer.jsx`

## Connections

- Home → Hero: renders
- Home → Public deals: shows
- Area deals → Deal grid: renders
- Deal detail → Exact price: opens
- Deal detail → Share deal: opens
- Deal detail → Alert setup: opens
- Dashboard → Dashboard client: hosts
- Dashboard client → Alerts list: composes
- Dashboard client → App store: uses
- Navbar → Auth routes: auth entry
- Data hooks → MCP routes: fetches data
- Data hooks → Alerts API: reads writes
- Data hooks → Shares API: reads writes
- Data hooks → Auth routes: session state
- Data hooks → App store: syncs
- MCP routes → MCP client: adapts
- Auth routes → Auth core: delegates
- Alerts API → Database: persists
- Shares API → Database: persists
- Alert cron → Database: loads rules
- Alert cron → MCP client: rechecks deals
- Alert cron → Queue: enqueues
- Workers → Queue: consumes
- Workers → Notifications: sends
- MCP client → Redis: caches
- Database → Redis: augments
- Exact price → MCP routes: simulates cart
- Share deal → Shares API: creates share
- Alert setup → Alerts API: creates alert
- Alerts list → Alerts API: lists alerts