# mikey958/contactless-pay-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/mikey958/contactless-pay-frontend
- Repository: https://github.com/mikey958/contactless-pay-frontend

## Overview

##### Project type and purpose
- This is a front-end single-page application (SPA) built with React and Vite.
- Its domain is public-transport info: browsing nearby stops, viewing transport details, managing favorites and history, and a map interface.

##### File structure
- Top-level: configuration files (vite.config.js, ESLint, Prettier, Stylelint), index.html, package.json.
- src/ contains:
- App entry (main.jsx, App.jsx)
- components (UI building blocks, organized by feature)
- layout (page wrappers: full, empty header, footer-only)
- pages (route-based views: Home, Search, Favorite, History, Map, Stop, Transport, etc.)
- contexts (ThemeContext) and hooks (useTheme)
- store (five JS stores for User, Transport, Favorite, History, Map state)
- utils (helpers, route definitions)
- styles (global CSS)
- No backend code; it consumes external transport or map APIs at runtime.

##### README
- Confirms minimal React+Vite template with HMR, ESLint preset, optional TypeScript.

##### Main components & interactions
a. Front-end SPA (browser)
- Vite Dev/Build Pipeline
- index.html → main.jsx → AppRouter
- Pages (Home, Search, Map, Favorite, History, Stop, Transport, etc.)
- Components (SearchBar, RouteSelect, TransportItem, Modal*, etc.)
- Layout wrappers (FullLayout, EmptyLayout, OnlyFooterLayout, etc.)
- Context layer (ThemeContext)
- State layer (UserStore, TransportStore, FavoriteStore, HistoryStore, MapStore)
- Utils (API wrappers, consts, route definitions)
b. External Services
- Public Transport API (GET stops, routes, real-time data)
- /Geo-location API (browser navigator.geolocation, map tiles)
c. Build & Deployment
- Vite Dev Server (HMR during development)
- Vite Build → dist/ (static assets) → deployed to a static host/CDN

d. Data & event flow
- User action in UI → Component event handler → calls store action → store uses utils → fetches from External API → updates store state → subscribed Components re-render.
- ThemeContext provides theming props to components.
- Router (AppRouter) determines which page layout and components to mount based on URL.

##### Architectural patterns & design principles
- Component-based UI with per-feature folders
- Declarative routing via AppRouter
- Centralized client-side state stores (MobX/Zustand-style pattern)
- Separation of concerns: UI <→ State <→ Data layer (utils/api)
- CSS Modules for encapsulated component styling
- Context for cross-cutting theming

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Layer
    subgraph "Build & Deployment"
        ViteConfig["vite.config.js"]:::build
        ViteDev["Vite Dev Server (HMR)"]:::build
        ViteBuild["Vite Build → dist/"]:::build
        StaticHost["Static Host/CDN"]:::build
    end

    %% App Initialization
    subgraph "App Initialization"
        HTML["index.html"]:::build
        Main["main.jsx"]:::ui
        App["App.jsx"]:::ui
        Router["AppRouter.jsx"]:::ui
    end

    %% Assets & Styles
    subgraph "Assets & Styles"
        Public["public/"]:::assets
        Assets["src/assets"]:::assets
        Styles["src/styles"]:::assets
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        Utils["src/utils"]:::data
        PTAPI["Public Transport API"]:::external
        MapAPI["Map/Geo-location API"]:::external
    end

    %% State Management Layer
    subgraph "State Management"
        UserStore["UserStore.js"]:::state
        TransportStore["TransportStore.js"]:::state
        FavoriteStore["FavoriteStore.js"]:::state
        HistoryStore["HistoryStore.js"]:::state
        MapStore["MapStore.js"]:::state
        ThemeContext["ThemeContext.js"]:::state
        UseTheme["useTheme.js"]:::state
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Pages["src/pages"]:::ui
        Components["src/components"]:::ui
        Layouts["src/layout"]:::ui
    end

    %% External Client
    Browser["Browser (React SPA)"]:::client

    %% Connections - Build & Deployment
    ViteDev -->|HMR| Browser
    ViteBuild --> StaticHost
    StaticHost -->|Serves| Browser
    ViteConfig --> ViteDev
    ViteConfig --> ViteBuild

    %% Connections - App Init
    HTML --> Main
    Main --> App
    App --> Router

    %% Assets & Styles Flow
    Public -->|bundled→| Browser
    Assets -->|bundled→| Browser
    Styles -->|bundled→| Browser

    %% UI Layer Flow
    Browser --> Router
    Router --> Pages
    Pages --> Components
    Pages --> Layouts

    %% State & Data Flow
    Components -->|dispatch action| UserStore
    Components -->|dispatch action| TransportStore
    Components -->|dispatch action| FavoriteStore
    Components -->|dispatch action| HistoryStore
    Components -->|dispatch action| MapStore

    UserStore -->|select data| Components
    TransportStore -->|select data| Components
    FavoriteStore -->|select data| Components
    HistoryStore -->|select data| Components
    MapStore -->|select data| Components

    UserStore --> Utils
    TransportStore --> Utils
    FavoriteStore --> Utils
    HistoryStore --> Utils
    MapStore --> Utils

    Utils --> PTAPI
    Utils --> MapAPI
    PTAPI -->|response| UserStore
    MapAPI -->|response| MapStore

    ThemeContext --> Components
    UseTheme --> Components

    %% Click Events
    click ViteConfig "https://github.com/mikey958/contactless-pay-frontend/blob/master/vite.config.js"
    click HTML "https://github.com/mikey958/contactless-pay-frontend/blob/master/index.html"
    click Main "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/main.jsx"
    click App "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/App.jsx"
    click Router "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/components/AppRouter.jsx"
    click Pages "https://github.com/mikey958/contactless-pay-frontend/tree/master/src/pages"
    click Components "https://github.com/mikey958/contactless-pay-frontend/tree/master/src/components"
    click Layouts "https://github.com/mikey958/contactless-pay-frontend/tree/master/src/layout"
    click ThemeContext "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/contexts/ThemeContext.js"
    click UseTheme "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/hooks/useTheme.js"
    click UserStore "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/store/UserStore.js"
    click TransportStore "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/store/TransportStore.js"
    click FavoriteStore "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/store/FavoriteStore.js"
    click HistoryStore "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/store/HistoryStore.js"
    click MapStore "https://github.com/mikey958/contactless-pay-frontend/blob/master/src/store/MapStore.js"
    click Utils "https://github.com/mikey958/contactless-pay-frontend/tree/master/src/utils"
    click Public "https://github.com/mikey958/contactless-pay-frontend/tree/master/public/"
    click Assets "https://github.com/mikey958/contactless-pay-frontend/tree/master/src/assets"
    click Styles "https://github.com/mikey958/contactless-pay-frontend/tree/master/src/styles"

    %% Styles
    classDef build fill:#dddddd,stroke:#888,stroke-width:1px;
    classDef ui fill:#bbdefb,stroke:#1976d2,stroke-width:1px;
    classDef state fill:#c8e6c9,stroke:#388e3c,stroke-width:1px;
    classDef data fill:#ffe0b2,stroke:#f57c00,stroke-width:1px;
    classDef assets fill:#e1bee7,stroke:#7b1fa2,stroke-width:1px;
    classDef external fill:#ffcdd2,stroke:#d32f2f,stroke-width:1px;
    classDef client fill:#f0f4c3,stroke:#afb42b,stroke-width:1px;
```
