# waintz/shopnest architecture

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

- Interactive diagram: https://gitdiagram.com/waintz/shopnest
- Repository: https://github.com/waintz/shopnest

## Overview

##### Project Type and Purpose
- This is a front-end single-page application (SPA) built with React, TypeScript, and Vite.
- It provides a minimal template with HMR, an API layer (with mock support via MSW), a query-client for data fetching/caching, and feature-based code organization.

##### File Structure
- Top-level files and folders:
- package.json, vite.config.ts – build and dev server configuration
- public/ & index.html – static assets & SPA entry point
- src/app/ – core application shell (App.tsx, router, providers, global CSS)
- src/features/ – feature modules (header, products-list pages)
- src/shared/ – shared code:
- api/ – HTTP client instance + MSW mocks + OpenAPI schema
- api/query-client.ts – React Query setup
- model/ – global config and route definitions
- lib/ – utility functions (e.g., CSS helpers)
- MSW mock handlers and the schema directory, indicating a development-time mock server.

##### README for Additional Insights
- Confirms the use of Vite with React or SWC plugins.
- Highlights ESLint configuration for production readiness.
- No backend code—data comes from either a real HTTP API (via shared/api/instance) or the local mock server in development.

##### Main Components
a. Vite Dev Server / Build Pipeline
- Plugins: @vitejs/plugin-react or plugin-react-swc
- Output: Bundles served to browser
b. Browser / Client
- index.html loads App, HMR enabled
c. React Application Shell (src/app)
- App.tsx – root React component
- Providers – React Query client, context providers
- Router – defines routes from shared/model/routes.ts
- ProtectedRoute – auth guard pattern
d. Feature Modules (src/features)
- Header feature – global navigation UI
- Products-List feature – page component fetching product data
e. Shared Services
- HTTP Client (instance.ts)
- React Query (query-client.ts)
- API Schema (OpenAPI YAML → generated.ts)
- MSW Mock Server (mocks/browser.ts + handlers)
f. External/Backend API
- Real HTTP endpoints (in production)
- Mocked endpoints (in development via MSW)

##### Relationships and Data Flows
- Browser requests index.html → Vite serves bundle → App mounts
- App registers Providers → QueryClient → Router
- Feature pages mount → call useQuery hooks → shared/api/instance issues HTTP requests
- In development: MSW intercepts requests, returns mock data
- In production: requests go to real backend URLs
- Responses flow back into React Query cache → UI components re-render

##### Architectural Patterns and Principles
- Modular, feature-based folder structure
- Clear separation of concerns:
- app (composition and routing)
- features (UI pages)
- shared (services, models, utilities)
- Dependency Injection via Providers
- Mocking layer via MSW integrated with the HTTP client
- API schema in OpenAPI format driving type generation

##### Technologies and Frameworks
- Vite (dev server/bundler)
- React + TypeScript
- @vitejs/plugin-react or react-swc
- React Router (router.tsx)
- React Query (query-client.ts)
- MSW (Mock Service Worker)
- OpenAPI codegen (schema/…)
- ESLint (eslint.config.js)

##### Don’t Overthink: Capture Every Logical Component
- Related files under the same component if needed (e.g., “API Schema & Mocks”)
- Flow of initialization (App startup), rendering (feature pages), and data fetching is explicit

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure
    ViteDev["Vite Dev Server / Build Pipeline"]:::infra
    Browser["Browser"]:::infra
    public["Public Assets (public/)"]:::infra

    ViteDev -->|"serves bundle & HMR"| Browser
    Browser -->|"loads"| public

    %% React App Shell
    subgraph "React Application Shell"
        AppMain["main.tsx"]:::app
        App["App.tsx"]:::app
        Providers["Providers"]:::app
        Router["Router"]:::app
        Protect["ProtectedRoute"]:::app
        GlobalCSS["Global CSS"]:::app
    end

    Browser -->|"mounts"| AppMain
    AppMain --> App
    App --> Providers
    Providers --> Router
    Router --> Protect

    %% Feature Modules
    subgraph "Feature Modules"
        Header["Header Feature"]:::feature
        ProductsList["Products-List Page"]:::feature
    end

    Router --> Header
    Router --> ProductsList

    %% Shared Services
    subgraph "Shared Services"
        HTTPClient["HTTP Client Instance"]:::service
        QueryClient["React Query Client"]:::service
        MSWBrowser["MSW Browser Setup"]:::service
        subgraph "MSW Mocks"
            HandlersProducts["Products Handler"]:::service
            HandlersHTTP["HTTP Handler"]:::service
            MocksIndex["Mocks Index"]:::service
        end
        subgraph "API Schema"
            SchemaMain["main.yaml"]:::service
            SchemaProd["products.yaml"]:::service
            SchemaGen["generated.ts"]:::service
            SchemaIndex["schema index"]:::service
        end
        Config["Global Config"]:::service
        RoutesDef["Route Definitions"]:::service
        EnvTypes["Environment Typings"]:::service
        CSSHelpers["CSS Helpers"]:::service
    end

    Header --> QueryClient
    ProductsList --> QueryClient
    QueryClient --> HTTPClient
    HTTPClient -->|"fetch (prod)"| RealAPI
    HTTPClient -->|"fetch (dev)"| MSWBrowser
    MSWBrowser -->|"uses handlers"| HandlersProducts
    MSWBrowser -->|"uses handlers"| HandlersHTTP
    RealAPI["Backend API"]:::external
    RealAPI -->|"response"| HTTPClient
    MSWBrowser -->|"mock response"| HTTPClient
    HTTPClient -->|"data"| QueryClient
    QueryClient -->|"data"| ProductsList

    %% Build & Lint Config
    subgraph "Build & Lint Configuration"
        PKG["package.json"]:::service
        ESLint["eslint.config.js"]:::service
        TSConfig["tsconfig.json & variants"]:::service
    end

    %% Click Events
    click ViteDev "https://github.com/waintz/shopnest/blob/main/vite.config.ts"
    click public "https://github.com/waintz/shopnest/tree/main/public/"
    click AppMain "https://github.com/waintz/shopnest/blob/main/src/app/main.tsx"
    click App "https://github.com/waintz/shopnest/blob/main/src/app/App.tsx"
    click Providers "https://github.com/waintz/shopnest/blob/main/src/app/providers.tsx"
    click Router "https://github.com/waintz/shopnest/blob/main/src/app/router.tsx"
    click Protect "https://github.com/waintz/shopnest/blob/main/src/app/protected-route.tsx"
    click GlobalCSS "https://github.com/waintz/shopnest/blob/main/src/app/index.css"
    click Header "https://github.com/waintz/shopnest/blob/main/src/features/header/index.tsx"
    click ProductsList "https://github.com/waintz/shopnest/blob/main/src/features/products-list/products-list.page.tsx"
    click HTTPClient "https://github.com/waintz/shopnest/blob/main/src/shared/api/instance.ts"
    click QueryClient "https://github.com/waintz/shopnest/blob/main/src/shared/api/query-client.ts"
    click MSWBrowser "https://github.com/waintz/shopnest/blob/main/src/shared/api/mocks/browser.ts"
    click HandlersProducts "https://github.com/waintz/shopnest/blob/main/src/shared/api/mocks/handlers/products.ts"
    click HandlersHTTP "https://github.com/waintz/shopnest/blob/main/src/shared/api/mocks/handlers/http.ts"
    click MocksIndex "https://github.com/waintz/shopnest/blob/main/src/shared/api/mocks/index.ts"
    click SchemaMain "https://github.com/waintz/shopnest/blob/main/src/shared/api/schema/main.yaml"
    click SchemaProd "https://github.com/waintz/shopnest/blob/main/src/shared/api/schema/endpoints/products.yaml"
    click SchemaGen "https://github.com/waintz/shopnest/blob/main/src/shared/api/schema/generated.ts"
    click SchemaIndex "https://github.com/waintz/shopnest/blob/main/src/shared/api/schema/index.ts"
    click Config "https://github.com/waintz/shopnest/blob/main/src/shared/model/config.ts"
    click RoutesDef "https://github.com/waintz/shopnest/blob/main/src/shared/model/routes.ts"
    click EnvTypes "https://github.com/waintz/shopnest/blob/main/src/shared/env.d.ts"
    click CSSHelpers "https://github.com/waintz/shopnest/blob/main/src/shared/lib/css.ts"
    click PKG "https://github.com/waintz/shopnest/blob/main/package.json"
    click ESLint "https://github.com/waintz/shopnest/blob/main/eslint.config.js"
    click TSConfig "https://github.com/waintz/shopnest/blob/main/tsconfig.json"

    %% Styles
    classDef infra fill:#f9f,stroke:#333,stroke-width:1px
    classDef app fill:#bbf,stroke:#333,stroke-width:1px
    classDef feature fill:#bfb,stroke:#333,stroke-width:1px
    classDef service fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#fbb,stroke:#333,stroke-width:1px
```
