How imaditya-jain/storepilot-ai works
1. Overall shape
StorePilot AI is a single Next.js App Router application that contains both the UI and the backend API. The repo is organized as a SaaS dashboard for Shopify merchants, with server-side API routes handling auth, store connection, product sync, and AI SEO generation.
2. Main user-facing surfaces
The UI is split into two route groups: authenticated dashboard pages and auth pages. Under app/(pages)/auth are login, register, forgot/reset password, and user verification flows. Under app/(pages)/dashboard are the core product and store views, including a product list, product detail page, and store connection page.
3. Backend API boundary
All backend behavior lives in app/api/v1. This is the main service boundary for the frontend. The API is divided into three domains: auth for session and account management, shopify for OAuth/store/product operations, and ai for SEO generation.
4. Authentication subsystem
Authentication is JWT-based with access and refresh tokens, HttpOnly cookies, and silent refresh support. The auth API includes login, register, logout, me, refresh-token, forgot-password, reset-password, verify-user, and username availability checks. The app/utils and lib auth helpers suggest token/cookie handling is shared between browser and server code, while app/components/auth/protected-route.tsx and the auth provider enforce route/session protection on the client.
5. Shopify integration subsystem
Shopify is the core external system. The repo includes OAuth connect/callback routes, store metadata endpoints, product listing and sync endpoints, and per-product SEO update routes. Helper modules under app/helpers/shopify handle installation URL generation, OAuth token exchange, Shopify client setup, shop-domain validation, and product fetching. This forms the boundary where Shopify remains the source of truth.
6. Product data flow
Product data is synchronized from Shopify into the app through cursor-based, chunked sync endpoints. The README and model layout indicate the app stores a lightweight cache rather than full product replicas. The product model likely contains optimized fields such as title, handle, featured image, SEO title/description, status, and timestamps, which are enough for dashboard rendering and AI workflows without mirroring all Shopify data.
7. AI SEO subsystem
AI generation is isolated behind app/api/v1/ai/generate-seo and shared helpers in app/helpers/ai. Prompt construction lives in app/helpers/ai/prompts.ts, and provider selection is abstracted in provider.ts, with app/lib/ai.ts acting as a higher-level integration layer. This subsystem takes a product context, produces SEO title/meta description suggestions, and feeds the result back into the Shopify product update flow.
8. State management and client data access
Client-side state is managed with Redux Toolkit under lib/store.ts, lib/slices, and lib/features. There are separate slices/features for auth, products, stores, and username availability. app/providers/auth-session-provider.tsx and app/providers/StoreProvider.tsx bridge server/session data into the client, while app/lib/auth-fetch.ts centralizes authenticated requests with token handling.
9. Data persistence and domain models
MongoDB is the backing store, with Mongoose-style models in app/models for users, stores, and products. Configuration is centralized in app/config/db.config.ts. This persistence layer supports multi-store SaaS behavior: users own stores, stores hold Shopify credentials/tokens, and products are linked to stores for isolation.
10. Supporting infrastructure
Email workflows for registration and password recovery are backed by Nodemailer configuration and mail helpers. Shared utilities under app/utils handle cookie/token generation and auth request concerns. The app also includes a service worker, manifest, global styles, and layout components that make the dashboard feel like a cohesive SaaS product rather than a collection of pages.
11. Presentation architecture
UI composition is split into reusable components for forms, layouts, product views, and Shopify connection views. app/components/layout/dashboard contains a structured sidebar/topbar shell for authenticated pages, while app/components/layout/auth provides the auth page shell. This keeps route pages thin and pushes most UI behavior into reusable, domain-specific components.
12. Key end-to-end flow
The dominant workflow is: authenticate the merchant, connect a Shopify store via OAuth, sync products into the local cache, select a product in the dashboard, generate AI SEO text, preview it, and save it back to Shopify. That flow crosses the main boundaries in the repo: browser UI → Next.js API routes → MongoDB/Redux state → Shopify GraphQL → AI provider → Shopify update.
Main entry points: shopify Shopify API · auth Auth API · models Domain models · ai AI API
Components 21
UI routes
User-facing pages and route shells
- App shell · Root layout, landing page, metadata, and app-wide wiring
app/layout.tsx - Auth pages · Login, register, password recovery, and verification screens
app/(pages)/auth - Dashboard pages · Authenticated product and store dashboard views
app/(pages)/dashboard
API v1
Backend routes for auth, Shopify, and AI
- Auth API · Login, register, session, refresh, and recovery endpoints
app/api/v1/auth - Shopify API · OAuth, store, product sync, and product SEO update endpoints
app/api/v1/shopify - AI API · SEO generation endpoint for product content
app/api/v1/ai
Shared app code
Reusable components, helpers, state, and providers
- Auth shell · Auth page layout and styling shell
app/components/layout/auth/layout.tsx - Dashboard shell · Sidebar and topbar frame for authenticated pages
app/components/layout/dashboard/layout.tsx - Route guard · Client-side session protection for private routes
app/components/auth/protected-route.tsx - Auth session · Hydrates and shares authenticated session state
app/providers/auth-session-provider.tsx - Store provider · Shares selected store and dashboard state
app/providers/StoreProvider.tsx - Redux store · Central client state container
lib/store.ts - Feature slices · Auth, products, stores, and username-check state
lib/slices - UI components · Forms, layouts, product views, and Shopify connection UI
app/components - Shopify helpers · Install URL, token exchange, client setup, validation, and product fetch helpers
app/helpers/shopify - AI helpers · Prompt construction and AI provider abstraction
app/helpers/ai - Auth utils · Cookie, token, and auth request helpers used on client and server
app/utils - Mail helpers · Nodemailer setup and transactional email helpers
app/helpers/mail - GraphQL ops · Shared Shopify query and mutation documents
app/graphQL
Data layer
Database config and domain models
- Domain models · User, store, and product persistence models
app/models - DB config · MongoDB connection configuration
app/config/db.config.ts
Connections 26
- App shell → Auth pages: routes · Exposes authentication screens
- App shell → Dashboard pages: routes · Exposes merchant dashboard screens
- Auth pages → Auth shell: uses · Wrapped by auth page shell
- Dashboard pages → Dashboard shell: uses · Rendered inside dashboard shell
- Dashboard pages → Route guard: protects · Requires authenticated session
- Route guard → Auth session: reads session · Uses hydrated auth state
- Auth session → Auth API: calls · Fetches me/refresh/session data
- UI components → Auth API: calls · Submits auth forms and session actions
- UI components → Shopify API: calls · Connects store, loads products, updates SEO
- UI components → AI API: calls · Requests SEO generation
- Auth API → Auth utils: uses · Sets and reads tokens/cookies
- Auth API → Domain models: persists · Stores users and auth-related state
- Auth API → Mail helpers: sends mail · Registration and password recovery emails
- Shopify API → Shopify helpers: uses · OAuth, client, validation, and product fetch logic
- Shopify API → Domain models: persists · Stores shops and product cache
- Shopify API → GraphQL ops: queries · Reads and mutates Shopify data
- Shopify API → Auth utils: authenticates · Uses tokens and request helpers
- AI API → AI helpers: uses · Builds prompts and selects provider
- AI API → Domain models: reads data · Loads product context for generation
- AI API → Shopify API: feeds updates · SEO output is applied back to product flow
- Redux store → Feature slices: composes · Combines feature state domains
- Feature slices → Auth session: hydrates · Stores auth/session state
- Feature slices → Store provider: hydrates · Stores selected store and dashboard state
- Feature slices → UI components: drives UI · Forms and views consume client state
- Shopify helpers → Domain models: supports · Backs store/product sync persistence
- DB config → Domain models: connects · Provides MongoDB access for models