# imaditya-jain/storepilot-ai architecture

> Architecture diagram of the GitHub repository imaditya-jain/storepilot-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imaditya-jain/storepilot-ai
- Repository: https://github.com/imaditya-jain/storepilot-ai

## Overview

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: [`app/api/v1/shopify`](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/shopify) (Shopify API), [`app/api/v1/auth`](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/auth) (Auth API), [`app/models`](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/models) (Domain models), [`app/api/v1/ai`](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/ai) (AI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI routes"]
  node_app_root["App shell<br/>nextjs app<br/>[layout.tsx]"]
  node_auth_pages["Auth pages<br/>route group"]
  node_dashboard_pages["Dashboard pages<br/>route group"]
end

subgraph group_api["API v1"]
  node_auth_api["Auth API<br/>REST auth"]
  node_shopify_api["Shopify API<br/>REST shopify"]
  node_ai_api["AI API<br/>REST ai"]
end

subgraph group_shared["Shared app code"]
  node_auth_layout["Auth shell<br/>layout<br/>[layout.tsx]"]
  node_dashboard_layout["Dashboard shell<br/>layout<br/>[layout.tsx]"]
  node_auth_guard["Route guard<br/>client auth"]
  node_auth_provider["Auth session<br/>provider"]
  node_store_provider["Store provider<br/>[StoreProvider.tsx]"]
  node_redux_store["Redux store<br/>state root<br/>[store.ts]"]
  node_feature_slices["Feature slices<br/>redux slices"]
  node_ui_components["UI components<br/>component kit"]
  node_shopify_helpers["Shopify helpers<br/>integration helpers"]
  node_ai_helpers["AI helpers<br/>prompt/provider"]
  node_auth_utils["Auth utils<br/>token/cookie utils"]
  node_mail_helpers["Mail helpers<br/>email service"]
  node_shopify_graphql["GraphQL ops<br/>shopify graphql"]
end

subgraph group_data["Data layer"]
  node_domain_models[("Domain models<br/>mongoose models")]
  node_db_config["DB config<br/>mongo config<br/>[db.config.ts]"]
end

node_app_root -->|"routes"| node_auth_pages
node_app_root -->|"routes"| node_dashboard_pages
node_auth_pages -->|"uses"| node_auth_layout
node_dashboard_pages -->|"uses"| node_dashboard_layout
node_dashboard_pages -->|"protects"| node_auth_guard
node_auth_guard -->|"reads session"| node_auth_provider
node_auth_provider -->|"calls"| node_auth_api
node_ui_components -->|"calls"| node_auth_api
node_ui_components -->|"calls"| node_shopify_api
node_ui_components -->|"calls"| node_ai_api
node_auth_api -->|"uses"| node_auth_utils
node_auth_api -->|"persists"| node_domain_models
node_auth_api -->|"sends mail"| node_mail_helpers
node_shopify_api -->|"uses"| node_shopify_helpers
node_shopify_api -->|"persists"| node_domain_models
node_shopify_api -->|"queries"| node_shopify_graphql
node_shopify_api -->|"authenticates"| node_auth_utils
node_ai_api -->|"uses"| node_ai_helpers
node_ai_api -->|"reads data"| node_domain_models
node_ai_api -.->|"feeds updates"| node_shopify_api
node_redux_store -->|"composes"| node_feature_slices
node_feature_slices -->|"hydrates"| node_auth_provider
node_feature_slices -->|"hydrates"| node_store_provider
node_feature_slices -->|"drives UI"| node_ui_components
node_shopify_helpers -.->|"supports"| node_domain_models
node_db_config -->|"connects"| node_domain_models

click node_app_root "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/layout.tsx"
click node_auth_pages "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/(pages)/auth"
click node_dashboard_pages "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/(pages)/dashboard"
click node_auth_layout "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/components/layout/auth/layout.tsx"
click node_dashboard_layout "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/components/layout/dashboard/layout.tsx"
click node_auth_guard "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/components/auth/protected-route.tsx"
click node_auth_api "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/auth"
click node_shopify_api "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/shopify"
click node_ai_api "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/ai"
click node_auth_provider "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/providers/auth-session-provider.tsx"
click node_store_provider "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/providers/StoreProvider.tsx"
click node_redux_store "https://github.com/imaditya-jain/storepilot-ai/blob/main/lib/store.ts"
click node_feature_slices "https://github.com/imaditya-jain/storepilot-ai/tree/main/lib/slices"
click node_ui_components "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/components"
click node_shopify_helpers "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/helpers/shopify"
click node_ai_helpers "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/helpers/ai"
click node_auth_utils "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/utils"
click node_domain_models "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/models"
click node_db_config "https://github.com/imaditya-jain/storepilot-ai/blob/main/app/config/db.config.ts"
click node_mail_helpers "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/helpers/mail"
click node_shopify_graphql "https://github.com/imaditya-jain/storepilot-ai/tree/main/app/graphQL"

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_app_root,node_auth_pages,node_dashboard_pages toneBlue
class node_auth_api,node_shopify_api,node_ai_api toneAmber
class node_auth_layout,node_dashboard_layout,node_auth_guard,node_auth_provider,node_store_provider,node_redux_store,node_feature_slices,node_ui_components,node_shopify_helpers,node_ai_helpers,node_auth_utils,node_mail_helpers,node_shopify_graphql toneMint
class node_domain_models,node_db_config toneRose
```

## Components

### UI routes

User-facing pages and route shells

- [App shell](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/layout.tsx): nextjs app · Root layout, landing page, metadata, and app-wide wiring · `app/layout.tsx`
- [Auth pages](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/(pages)/auth): route group · Login, register, password recovery, and verification screens · `app/(pages)/auth`
- [Dashboard pages](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/(pages)/dashboard): route group · Authenticated product and store dashboard views · `app/(pages)/dashboard`

### API v1

Backend routes for auth, Shopify, and AI

- [Auth API](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/auth): REST auth · Login, register, session, refresh, and recovery endpoints · `app/api/v1/auth`
- [Shopify API](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/shopify): REST shopify · OAuth, store, product sync, and product SEO update endpoints · `app/api/v1/shopify`
- [AI API](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/api/v1/ai): REST ai · SEO generation endpoint for product content · `app/api/v1/ai`

### Shared app code

Reusable components, helpers, state, and providers

- [Auth shell](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/components/layout/auth/layout.tsx): layout · Auth page layout and styling shell · `app/components/layout/auth/layout.tsx`
- [Dashboard shell](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/components/layout/dashboard/layout.tsx): layout · Sidebar and topbar frame for authenticated pages · `app/components/layout/dashboard/layout.tsx`
- [Route guard](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/components/auth/protected-route.tsx): client auth · Client-side session protection for private routes · `app/components/auth/protected-route.tsx`
- [Auth session](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/providers/auth-session-provider.tsx): provider · Hydrates and shares authenticated session state · `app/providers/auth-session-provider.tsx`
- [Store provider](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/providers/StoreProvider.tsx): provider · Shares selected store and dashboard state · `app/providers/StoreProvider.tsx`
- [Redux store](https://github.com/imaditya-jain/storepilot-ai/blob/main/lib/store.ts): state root · Central client state container · `lib/store.ts`
- [Feature slices](https://github.com/imaditya-jain/storepilot-ai/tree/main/lib/slices): redux slices · Auth, products, stores, and username-check state · `lib/slices`
- [UI components](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/components): component kit · Forms, layouts, product views, and Shopify connection UI · `app/components`
- [Shopify helpers](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/helpers/shopify): integration helpers · Install URL, token exchange, client setup, validation, and product fetch helpers · `app/helpers/shopify`
- [AI helpers](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/helpers/ai): prompt/provider · Prompt construction and AI provider abstraction · `app/helpers/ai`
- [Auth utils](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/utils): token/cookie utils · Cookie, token, and auth request helpers used on client and server · `app/utils`
- [Mail helpers](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/helpers/mail): email service · Nodemailer setup and transactional email helpers · `app/helpers/mail`
- [GraphQL ops](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/graphQL): shopify graphql · Shared Shopify query and mutation documents · `app/graphQL`

### Data layer

Database config and domain models

- [Domain models](https://github.com/imaditya-jain/storepilot-ai/tree/main/app/models): mongoose models · User, store, and product persistence models · `app/models`
- [DB config](https://github.com/imaditya-jain/storepilot-ai/blob/main/app/config/db.config.ts): mongo config · MongoDB connection configuration · `app/config/db.config.ts`

## Connections

- 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
