# etereo-io/vite-react-ts-scaffolding architecture

> Architecture diagram of the GitHub repository etereo-io/vite-react-ts-scaffolding, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/etereo-io/vite-react-ts-scaffolding
- Repository: https://github.com/etereo-io/vite-react-ts-scaffolding

## Overview

##### Project type and purpose
- This is a front-end single-page application (SPA) scaffold built with React, TypeScript, Vite, Tailwind, React Query, i18next, Zustand, and MSW.
- It provides a ready-made architecture for routing, state management, data fetching, internationalization, theming, feature modules, testing, linting, and mock APIs.

##### File structure
- Top-level:
– public/: Static assets, mockServiceWorker, robots.txt
– src/: Source code
– config/: YAML config for dev, local, prod
– .husky, .github, tasks.md, etc. for tooling and CI/CD
- src/app/: Core app bootstrap—App.tsx, AppRoutes.tsx, providers
- src/app/features/: Cross-cutting features—auth, config loader, i18n, mock-server
- src/features/: Domain features—dashboard, orders, etc.
- src/lib/: Reusable low-level libraries—metrics, notifications, queryparams helpers
- src/shared/: Shared UI components and layouts
- src/main.tsx: Entrypoint that mounts App into the DOM

##### Extract architecture insights from README
- Core stack: React + Vite + TS
- Routing: React Router DOM
- State Mgmt: Zustand & React Query
- i18n: i18next
- Mock API: MSW (mockServiceWorker)
- Build & Dev: Vite dev server, npm scripts for build/test/lint/coverage

##### Main components
A. Development & Build Tools
- Vite Dev Server
- npm scripts (start, build, lint, test)
- Husky, lint-staged, Biome for pre-commit
B. Runtime Environment
- Browser (Client)
- React SPA (bundle served by Vite/production static files)
C. React Application Layers
1. Entrypoint (main.tsx)
2. Core App Component (App.tsx)
3. Providers Layer
– ConfigProvider (loads config.dev.yml, etc.)
– I18nProvider (i18next initialization, locale loader)
– QueryClientProvider (React Query client)
– AuthProvider (Zustand or custom auth context)
– MockProvider (MSW integration in development)
4. Routing (AppRoutes.tsx using React Router)
5. Feature Modules (folder-per-feature)
– Dashboard (UI components: Chart, Deposits; pages: DashboardPage)
– Orders (hooks: useOrders, services: orders.services.ts, pages: OrdersPage)
– Shared & Lib usage (metrics, notifications, queryparams)
D. External Dependencies & Services
- Real APIs (fetched via src/app/features/api/api.ts)
- Mock API (MSW) in dev mode intercepting requests
- Third-party libraries (React Router, Tailwind, i18next, Zustand, React Query)

##### Relationships & data flows
- Browser → Vite Dev Server (during dev) → serves bundle → mounts React SPA
- React SPA → ConfigProvider (reads config) → supplies settings
- React SPA → I18nProvider → loads locale JSON → renders UI in correct language
- React SPA → MockProvider in dev (intercepts fetch/XHR) → returns mock data
- React SPA → QueryClient → executes hooks (useOrders, useMetrics) → fetches from real or mock APIs
- Feature Component → Shared UI Components (e.g., AdminLayout, Title)
- Hooks & Services → Business logic & network calls → feed into components
- Build pipeline (npm run build) → Vite bundles → outputs static assets in dist/

##### Architectural patterns & design principles
- Feature-driven folder structure (“module per folder”)
- Provider pattern (React Context for config, auth, i18n, mock)
- Separation of concerns: UI components, hooks/services, types/constants, assets
- Dependency injection via Providers
- Mock-first development using MSW
- Single source of truth for config, types, constants
- Reusable “lib” for cross-feature utilities
- Strict typing with TypeScript types in @types and src/@types

##### Details
- Every provider and its role.
- Both mock and real API endpoints, and how MSW swaps in development.
- Flow of configuration (config/*.yml) into the ConfigProvider and into the app.
- How shared/lib folders feed into features to highlight reuse.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Dev Tools & Build Pipeline
    subgraph "Dev & Build Tools"
        direction TB
        VITE["Vite Dev Server"]:::tool
        PKG["npm Scripts\n(package.json)"]:::tool
        HUSKY["Husky Git Hooks"]:::tool
    end

    %% Public & Config
    subgraph "Static & Config"
        direction TB
        PUBLIC["Public Folder"]:::static
        CONFIG_YML["Config YAML Files"]:::config
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        direction TB
        BROWSER["Browser (Client)"]:::external
    end

    %% Application Layer
    subgraph "React Application"
        direction TB
        ENTRY["Entrypoint\n(main.tsx)"]:::app
        APP["Core App Component\n(App.tsx)"]:::app
        PROVIDERS["Providers Layer\n(AppProviders.tsx)"]:::provider
        ROUTES["Routing Layer\n(AppRoutes.tsx)"]:::routing

        subgraph "Providers"
            direction TB
            CONF_PROV["ConfigProvider"]:::provider
            I18N_LOADER["I18nLoader"]:::provider
            LOCALE_SEL["LocaleSelector"]:::provider
            QUERY_PROV["QueryClientProvider"]:::provider
            AUTH_PROV["AuthProvider"]:::provider
            MOCK_PROV["MockProvider"]:::provider
        end

        subgraph "Features"
            direction TB
            DASH["Dashboard Module"]:::feature
            ORD["Orders Module"]:::feature
        end

        SUB_SHARED["Shared UI & Layouts"]:::shared
        LIB["Utility Libraries"]:::lib
    end

    %% Service Layer
    subgraph "APIs & Mocks"
        direction TB
        REAL_API["Real API Module"]:::external
        MOCK_API["Mock API (MSW)"]:::external
    end

    %% Flows
    VITE --> PKG
    VITE --> PUBLIC
    PKG --> HUSKY

    BROWSER --> ENTRY
    ENTRY --> APP
    APP --> PROVIDERS
    PROVIDERS --> ROUTES
    ROUTES --> DASH
    ROUTES --> ORD

    PROVIDERS --> CONF_PROV
    PROVIDERS --> I18N_LOADER
    PROVIDERS --> LOCALE_SEL
    PROVIDERS --> QUERY_PROV
    PROVIDERS --> AUTH_PROV
    PROVIDERS --> MOCK_PROV

    CONF_PROV --> CONFIG_YML
    I18N_LOADER --> PUBLIC
    I18N_LOADER --> LOCALE_SEL
    QUERY_PROV --> LIB
    AUTH_PROV --> LIB
    MOCK_PROV --> MOCK_API

    DASH --> SUB_SHARED
    ORD --> SUB_SHARED
    DASH --> LIB
    ORD --> LIB

    DASH --> REAL_API
    ORD --> REAL_API

    REAL_API -->|Intercepted by| MOCK_API

    %% Click Events
    click VITE "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/vite.config.ts"
    click PKG "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/package.json"
    click HUSKY "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/.husky/pre-commit"
    click HUSKY "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/.husky/commit-msg"
    click PUBLIC "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/public/"
    click CONFIG_YML "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/config/config.dev.yml"
    click CONFIG_YML "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/config/config.local.yml"
    click CONFIG_YML "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/config/config.pro.yml"
    click ENTRY "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/main.tsx"
    click APP "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/components/App.tsx"
    click ROUTES "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/components/AppRoutes.tsx"
    click PROVIDERS "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/components/AppProviders.tsx"
    click CONF_PROV "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/features/config/providers/ConfigProvider.tsx"
    click I18N_LOADER "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/features/i18n/components/I18nLoader.tsx"
    click LOCALE_SEL "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/features/i18n/components/LocaleSelector.tsx"
    click QUERY_PROV "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/features/queryClient.ts"
    click MOCK_PROV "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/features/mock-server/providers/MockProvider.tsx"
    click REAL_API "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/app/features/api/api.ts"
    click DASH "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/src/features/dashboard"
    click ORD "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/src/features/orders"
    click SUB_SHARED "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/src/shared/components"
    click SUB_SHARED "https://github.com/etereo-io/vite-react-ts-scaffolding/blob/main/src/shared/layouts/AdminLayout.tsx"
    click LIB "https://github.com/etereo-io/vite-react-ts-scaffolding/tree/main/src/lib"

    %% Styles
    classDef tool fill:#f0f0f0,stroke:#ccc
    classDef static fill:#e8e8e8,stroke:#bbb,stroke-dasharray: 2 2
    classDef config fill:#fff2cc,stroke:#e6b800
    classDef external fill:#ffe0b2,stroke:#ff9800
    classDef app fill:#bbdefb,stroke:#2196f3
    classDef provider fill:#90caf9,stroke:#1e88e5
    classDef routing fill:#64b5f6,stroke:#1976d2
    classDef feature fill:#c8e6c9,stroke:#43a047
    classDef shared fill:#dcedc8,stroke:#7cb342
    classDef lib fill:#f0f4c3,stroke:#c0ca33
```
