# roarnald/bread-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/roarnald/bread-tracker
- Repository: https://github.com/roarnald/bread-tracker

## Overview

##### Project Type and Purpose
- This is a frontend-only Single Page Application (SPA) built with React, Parcel, TypeScript, Tailwind CSS and React Router.
- It consumes the CoinGecko public API to display real-time cryptocurrency prices.
- It persists a user’s custom token list in localStorage or encodes it in the URL.

##### High-Level Architectural Components
a. Client Application (Browser)
- React SPA served by Parcel development/build tools.
- Routes managed by React Router.
- UI styled with Tailwind CSS.
b. State Management
- A HomeContext/HomeProvider (React Context + Hooks) that holds the user’s token list and current prices.
c. API Layer
- src/api: Coins.ts and Simple.ts wrap calls to CoinGecko REST endpoints.
- src/utils/request.ts handles HTTP requests (fetch wrappers, error handling).
d. Persistence Layer
- LocalStorage or URL query params (via Utility HOC ProviderHOC.tsx) to persist/rehydrate the user’s token list.
e. External Service
- CoinGecko public API.

##### Relationships & Data Flow
1. User opens the SPA → index.html loads bundle → React renders the root `<App>` (src/components/index.tsx).
2. `<HomeProvider>` initializes state by reading localStorage or URL params.
3. Home UI components (HomeSearchBar, HomeTokenList, PinTitleButton, etc.) dispatch actions or call context methods.
4. Context calls src/api methods (Coins.list, Simple.price) via src/utils/request, awaiting JSON from CoinGecko.
5. On success, context updates its internal state and re-renders UI.
6. On list changes, context writes back to localStorage or updates the URL.

##### Key Architectural Patterns & Principles
- Component-based UI (React) separated into presentational (HomeTokenList, Footer) vs container/provider (HomeContext).
- Single source of truth in React Context.
- External API isolation in dedicated modules (`src/api`).
- Utility layers for HTTP requests and lazy loading.
- CSS-in-JS approach using Tailwind (via postcss, tailwind.config.js).

- Browser / Client
- React SPA (subdivide into “UI Components,” “React Router,” “Context Providers,” “Utils”)
- Persistence (LocalStorage / URL)
- External Service (CoinGecko API)
- User → UI Components
- UI Components → Context Provider → API Layer → External Service
- API responses back up the chain → UI
- Context → Persistence layer (read/write)
- UI: React, TypeScript, Tailwind CSS
- Routing: React Router
- Bundler: Parcel
- API Layer: src/api, fetch utils
- Persistence: localStorage / URL Params
- External Service: CoinGecko REST
- Blue rectangles for in-browser components (UI, Context, Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User([User]):::actor
    Entry["index.html"]:::frontend
    User -->|opens SPA| Entry
    Entry --> Parcel["Parcel Bundler"]:::bundle
    Parcel --> App["<App>"]:::frontend

    subgraph "React SPA"
        Router["React Router"]:::frontend
        App --> Router

        subgraph "UI Components"
            HomeContainer["HomeContainer"]:::frontend
            SearchBar["HomeSearchBar"]:::frontend
            TokenList["HomeTokenList"]:::frontend
            PinButton["PinTitleButton"]:::frontend
            Footer["Footer"]:::frontend
            Spinner["LoadingSpinner"]:::frontend
        end

        Router --> HomeContainer
        HomeContainer --> SearchBar
        HomeContainer --> TokenList
        TokenList --> PinButton
        HomeContainer --> Footer
        HomeContainer --> Spinner

        subgraph "Context & State"
            HomeProvider["HomeProvider"]:::frontend
            HomeContext["HomeContext"]:::frontend
        end

        HomeContainer --> HomeProvider
        HomeProvider --> HomeContext

        subgraph "API Layer"
            CoinsAPI["Coins.ts"]:::api
            SimpleAPI["Simple.ts"]:::api
        end

        HomeContext -->|"fetch via request"| Request
        Request["request.ts"]:::util
        Request --> CoinsAPI
        Request --> SimpleAPI
        CoinsAPI --> External
        SimpleAPI --> External

        subgraph "Utilities"
            ProviderHOC["ProviderHOC.tsx"]:::util
            Lazy["lazy.tsx"]:::util
            Common["Common.ts"]:::util
        end

        HomeContext --> ProviderHOC
        HomeContext --> Lazy
        HomeContext --> Common

        Persistence(("LocalStorage / URL Params")):::persistence
        HomeContext -->|reads/writes| Persistence

    end

    External["CoinGecko REST API"]:::external

    subgraph "Styling & Assets"
        Tailwind["tailwind.config.js"]:::config
        PostCSS["postcss.config.js"]:::config
        CSS["main.css"]:::config
        Assets["src/assets/img/"]:::config
    end

    subgraph "Types"
        Types["global.d.ts"]:::config
    end

    click Entry "https://github.com/roarnald/bread-tracker/blob/master/src/index.html"
    click App "https://github.com/roarnald/bread-tracker/blob/master/src/components/index.tsx"
    click HomeContainer "https://github.com/roarnald/bread-tracker/blob/master/src/components/Home/index.tsx"
    click SearchBar "https://github.com/roarnald/bread-tracker/blob/master/src/components/Home/HomeSearchBar.tsx"
    click TokenList "https://github.com/roarnald/bread-tracker/blob/master/src/components/Home/HomeTokenList/index.tsx"
    click PinButton "https://github.com/roarnald/bread-tracker/blob/master/src/components/Home/HomeTokenList/PinTitleButton.tsx"
    click Footer "https://github.com/roarnald/bread-tracker/blob/master/src/components/Public/Footer.tsx"
    click Spinner "https://github.com/roarnald/bread-tracker/blob/master/src/components/Public/Loading.tsx"
    click HomeContext "https://github.com/roarnald/bread-tracker/blob/master/src/contexts/Home/HomeContext.tsx"
    click HomeProvider "https://github.com/roarnald/bread-tracker/blob/master/src/contexts/Home/HomeProvider.tsx"
    click CoinsAPI "https://github.com/roarnald/bread-tracker/blob/master/src/api/Coins.ts"
    click SimpleAPI "https://github.com/roarnald/bread-tracker/blob/master/src/api/Simple.ts"
    click Request "https://github.com/roarnald/bread-tracker/blob/master/src/utils/request.ts"
    click ProviderHOC "https://github.com/roarnald/bread-tracker/blob/master/src/utils/ProviderHOC.tsx"
    click Lazy "https://github.com/roarnald/bread-tracker/blob/master/src/utils/lazy.tsx"
    click Common "https://github.com/roarnald/bread-tracker/blob/master/src/utils/Common.ts"
    click CSS "https://github.com/roarnald/bread-tracker/blob/master/src/css/main.css"
    click Types "https://github.com/roarnald/bread-tracker/blob/master/src/types/global.d.ts"

    classDef frontend fill:#cce5ff,stroke:#004085
    classDef api fill:#d1ecf1,stroke:#0c5460
    classDef util fill:#e2e3e5,stroke:#6c757d
    classDef persistence fill:#d4edda,stroke:#155724
    classDef external fill:#fff3cd,stroke:#856404
    classDef bundle fill:#f8d7da,stroke:#721c24
    classDef config fill:#e2e3e5,stroke:#6c757d
    classDef actor fill:#fefefe,stroke:#333,stroke-dasharray:2 2
```
