tush1504/coupon-hunter

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.