# jorgejimenez98/marlins-affiliates-tracker architecture

> Architecture diagram of the GitHub repository jorgejimenez98/marlins-affiliates-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jorgejimenez98/marlins-affiliates-tracker
- Repository: https://github.com/jorgejimenez98/marlins-affiliates-tracker

## Overview

##### Project type and purpose
- This is a front-end, single-page application built with React and Vite.
- It’s a PWA that tracks Miami Marlins and their minor league affiliates’ games.
- It consumes external game data (MLB or mock) via HTTP endpoints, supports i18n, then renders a responsive UI.

##### File structure
- Top level
- public/ – static assets, PWA manifest, images and docs
- src/ – application code
- vite.config.ts, tsconfig*.json – build configuration
- .env.example, vercel.json – environment and deployment settings
- src/components – reusable UI (common, layouts, shadcn-based UI primitives)
- src/features – route-level features (404, schedule page)
- src/lib – constants (endpoints, URLs), utilities (axios wrapper, i18n initializer)
- src/hooks – custom React hooks (routing, scroll detection, locale)
- src/providers – context providers (theme, i18n)
- src/stores – global state (using Zustand for date selection, etc.)
- src/main.tsx, index.html – SPA entry point
- package.json – dependencies (React, TanStack Query, Zustand, Tailwind, etc.)

##### README for additional insights
- Confirms React + Vite + TypeScript + Tailwind + Shadcn UI + TanStack Query + Zustand
- PWA support (installable app shell, service worker)
- External data source with optional mock data toggle via VITE_MOCK_DATA_ENABLED
- Deployment target: Vercel

a. Main components
- Browser / PWA shell
- Static hosting / CDN (Vercel)
- Service Worker (caching, offline support)
- React App
– Entry (index.html → main.tsx)
– Providers (theme, i18n)
– Global state store (Zustand)
– API layer (axios wrapper + TanStack Query)
– UI layer
· Common components (buttons, cards, date-picker, loader …)
· Layouts (header, footer)
· Features (schedule view, game tiles, filters)
- External API (MLB endpoints or mock data)
b. Relationships and interactions
- On load: Browser fetches index.html from Vercel CDN
- main.tsx → initialize providers → hydrate React tree
- React feature components call hooks (useGamesQuery)
- Hooks use TanStack Query + axios wrapper to fetch from external endpoints or mock server
- Zustand store holds local UI state (selected date, filters)
- UI updates and state flows via props, context, and hooks
- Service worker intercepts requests, caches assets and API responses for offline/PWA
c. Architectural patterns and design principles
- Component-based UI (atomic to composite)
- Feature modules (each route under src/features)
- Separation of concerns: UI vs. data fetching vs. state management vs. config
- PWA app shell pattern
d. Key technologies
- React + TypeScript (view layer)
- Vite (build & dev server)
- Tailwind CSS + Shadcn UI (styling)
- TanStack Query (data fetching/caching)
- Axios wrapper (HTTP client)
- Zustand (global state)
- i18n utility (locales under src/lib/locales)
- Vercel (CDN + serverless hosting)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        Browser["Browser / PWA Shell"]:::infra
        CDN["Static Hosting / CDN (Vercel)"]:::infra
        SW["Service Worker"]:::infra
    end

    %% App Shell Layer
    subgraph "PWA App Shell"
        direction TB
        Browser -->|"fetch assets"| CDN
        Browser -->|"register"| SW
    end

    %% React App Entry
    subgraph "React App Entry" 
        direction TB
        IndexHTML["index.html"]:::config
        MainTSX["src/main.tsx"]:::config
        AppTSX["src/App.tsx"]:::config
    end

    CDN -->|"serve"| IndexHTML
    IndexHTML -->|"bootstrap"| MainTSX
    MainTSX -->|"render"| AppTSX

    %% Providers Layer
    subgraph "Providers" 
        direction TB
        ThemeProv["ThemeProvider"]:::provider
        I18nProv["I18nProvider"]:::provider
    end
    AppTSX -->|"wraps with"| ThemeProv
    AppTSX -->|"wraps with"| I18nProv

    %% State Management Layer
    subgraph "Global State (Zustand)" 
        direction TB
        StoreIndex["src/stores/index.ts"]:::data
        DateStore["src/stores/use-date-store.ts"]:::data
    end
    ThemeProv -->|"provides context"| StoreIndex
    I18nProv --> StoreIndex
    StoreIndex --> DateStore

    %% Data Fetching Layer
    subgraph "API Layer & Data Fetching"
        direction TB
        AxiosWrapper["src/lib/utils/axios.ts"]:::data
        EndpointsConst["src/lib/constants/endpoints.constants.ts"]:::data
        UseGamesQuery["src/features/schedule/hooks/use-games-query.ts"]:::data
    end
    DateStore -->|"selected date"| UseGamesQuery
    UseGamesQuery -->|"http call via"| AxiosWrapper
    AxiosWrapper -->|"urls from"| EndpointsConst

    %% i18n Utility Layer
    subgraph "i18n Utility & Locales"
        direction TB
        I18nUtil["src/lib/utils/i18n.ts"]:::data
        CommonEN["src/lib/locales/en/common.json"]:::data
        CommonES["src/lib/locales/es/common.json"]:::data
    end
    I18nProv -->|"init"| I18nUtil
    I18nUtil --> CommonEN
    I18nUtil --> CommonES

    %% Routing & Features
    subgraph "Routing & Features"
        direction TB
        Router["src/features/main-router.routes.tsx"]:::feature
        NotFound["src/features/404/Index.tsx"]:::feature
        SchedulePage["src/features/schedule/Index.tsx"]:::feature
    end
    AppTSX -->|"defines routes"| Router
    Router --> SchedulePage
    Router --> NotFound

    %% Schedule Feature Modules
    subgraph "Schedule Feature Modules"
        direction TB
        SchComponents["src/features/schedule/components"]:::feature
        SchConstants["src/features/schedule/constants"]:::feature
        SchHelpers["src/features/schedule/helpers"]:::feature
        SchHooks["src/features/schedule/hooks"]:::feature
        SchTypes["src/features/schedule/types"]:::feature
    end
    SchedulePage --> SchComponents
    SchedulePage --> SchConstants
    SchedulePage --> SchHelpers
    SchedulePage --> SchHooks
    SchedulePage --> SchTypes

    %% Custom Hooks
    subgraph "Custom Hooks"
        direction TB
        AppRoutesHook["src/hooks/use-application-routes.tsx"]:::hook
        DateLocaleHook["src/hooks/use-date-locale.ts"]:::hook
        ScrolledHook["src/hooks/use-scrolled.ts"]:::hook
    end
    SchedulePage --> AppRoutesHook
    SchedulePage --> DateLocaleHook
    SW --> ScrolledHook

    %% UI Components
    subgraph "UI Layer"
        direction TB
        CommonUI["src/components/common"]:::ui
        LayoutHeader["src/components/layouts/header"]:::ui
        LayoutFooter["src/components/layouts/footer"]:::ui
        ShadcnPrims["src/components/ui"]:::ui
    end
    SchedulePage --> CommonUI
    SchedulePage --> LayoutHeader
    SchedulePage --> LayoutFooter
    SchedulePage --> ShadcnPrims

    %% Styling & Assets
    subgraph "Styling & Assets"
        direction TB
        IndexCSS["src/index.css"]:::config
        PublicDir["public/"]:::infra
    end
    MainTSX --> IndexCSS
    Browser --> PublicDir

    %% External API
    ExternalAPI["External MLB API or Mock"]:::infra
    UseGamesQuery -->|"fetches data from"| ExternalAPI
    SW -->|"caches requests"| ExternalAPI

    %% Config & Build
    subgraph "Config & Build"
        direction TB
        EnvConst["src/lib/constants/env.constants.ts"]:::config
        MockConst["src/lib/constants/mock-data.constants.ts"]:::config
        ViteConfig["vite.config.ts"]:::config
        TSConfig["tsconfig.json"]:::config
        EnvExample[".env.example"]:::config
    end
    ViteConfig -->|"build settings"| MainTSX
    EnvConst -->|"env vars"| AxiosWrapper
    MockConst -->|"toggle mock"| UseGamesQuery

    %% Click Events
    click Browser "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/public/"
    click CDN "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/vercel.json"
    click IndexHTML "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/index.html"
    click MainTSX "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/main.tsx"
    click AppTSX "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/App.tsx"
    click ThemeProv "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/providers/theme-provider.tsx"
    click I18nProv "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/providers/index.ts"
    click StoreIndex "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/stores/index.ts"
    click DateStore "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/stores/use-date-store.ts"
    click AxiosWrapper "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/utils/axios.ts"
    click EndpointsConst "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/constants/endpoints.constants.ts"
    click UseGamesQuery "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/features/schedule/hooks/use-games-query.ts"
    click I18nUtil "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/utils/i18n.ts"
    click CommonEN "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/locales/en/common.json"
    click CommonES "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/locales/es/common.json"
    click EnvConst "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/constants/env.constants.ts"
    click MockConst "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/lib/constants/mock-data.constants.ts"
    click ViteConfig "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/vite.config.ts"
    click TSConfig "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/tsconfig.json"
    click EnvExample "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/.env.example"
    click Router "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/features/main-router.routes.tsx"
    click NotFound "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/features/404/Index.tsx"
    click SchedulePage "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/features/schedule/Index.tsx"
    click SchComponents "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/features/schedule/components"
    click SchConstants "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/features/schedule/constants"
    click SchHelpers "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/features/schedule/helpers"
    click SchHooks "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/features/schedule/hooks"
    click SchTypes "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/features/schedule/types"
    click AppRoutesHook "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/hooks/use-application-routes.tsx"
    click DateLocaleHook "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/hooks/use-date-locale.ts"
    click ScrolledHook "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/hooks/use-scrolled.ts"
    click CommonUI "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/components/common"
    click LayoutHeader "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/components/layouts/header"
    click LayoutFooter "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/components/layouts/footer"
    click ShadcnPrims "https://github.com/jorgejimenez98/marlins-affiliates-tracker/tree/main/src/components/ui"
    click IndexCSS "https://github.com/jorgejimenez98/marlins-affiliates-tracker/blob/main/src/index.css"

    %% Styles
    classDef infra fill:#FDE68A,stroke:#F59E0B,color:#000
    classDef config fill:#E5E7EB,stroke:#9CA3AF,color:#000
    classDef provider fill:#DBEAFE,stroke:#3B82F6,color:#000
    classDef data fill:#D1FAE5,stroke:#10B981,color:#000
    classDef feature fill:#FCE7F3,stroke:#EC4899,color:#000
    classDef hook fill:#E0E7FF,stroke:#6366F1,color:#000
    classDef ui fill:#BFDBFE,stroke:#2563EB,color:#000
```
