# cooper-kerr/financial-bubble-detection-dashboard architecture

> Architecture diagram of the GitHub repository cooper-kerr/financial-bubble-detection-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cooper-kerr/financial-bubble-detection-dashboard
- Repository: https://github.com/cooper-kerr/financial-bubble-detection-dashboard

## Overview

##### Project type and purpose
- This is a client-centric single-page application (SPA) built in React/TypeScript, bundled by Vite and deployed on Vercel.

##### High-level file-structure analysis
- Top-level config & metadata: package.json, bun.lock, tsconfig.json, vite.config.ts, vercel.json, biome.json.
- Source code: /src
- components/ — React UI pieces (Dashboard, charts, controls, shadcn/ui primitives)
- hooks/ — custom data-loading hook (useDashboardData)
- routes/ — TanStack Router layouts & pages
- lib/ & utils/ — shared utilities and data-loader logic
- types/ — TypeScript interfaces for BubbleData
- styles/ — Tailwind CSS imports and custom styles
- main.tsx + reportWebVitals.ts — app entry + performance measurement
- routeTree.gen.ts — auto-generated routing structure
- Scripts: /scripts — Node/TypeScript utilities for uploading, fetching, and managing blob data.
- Docs: BLOB_SETUP.md, any additional guides.
- Build output: /dist after production build.

##### Key insights from README
- React 19 + TypeScript SPA, Vite for hot reload, Bun as package manager.
- TanStack Router file-based routing pattern.
- Plotly.js for charts, Tailwind + shadcn/ui for styling.
- Vercel Blob Storage for JSON data serving.
- Local development vs. production build commands.
- No custom backend service; data is pre-computed offline and uploaded via scripts.

##### Main architectural components
a. Frontend SPA (React + Vite)
- UI Layer: components, theming, routing
- Data-fetching Layer: useDashboardData hook, dataLoader.ts, fetch from blob URLs
- Chart Layer: PlotlyBubbleChart, PriceDifferenceChart
b. Cloud Data Storage
- Vercel Blob Storage bucket hosting JSON files
- Scripts (upload-to-blob.ts, get-blob-urls.ts, etc.) for data management
c. Build & Deployment
- Vite bundler, Bun runtime, CI/CD on Vercel (vite.config.ts, vercel.json)
d. Developer Tools
- Biome linter/formatter, Vitest for tests, .vscode settings

##### Relationships and data flows
- User browser ⇄ Vercel CDN serves index.html & static assets
- React app bootstraps (main.tsx) → TanStack Router → Dashboard route
- DashboardControls component triggers useDashboardData hook → HTTP GET to blob URLs → JSON bubble data
- DataLoader.ts transforms raw JSON → typed BubbleData → passed to Chart components
- Chart components render interactive Plotly graphs → user interactions (zoom, date pickers) update state → re-render
- Vite dev server provides hot-reload; Bun commands handle build & serve.
- Scripts run offline (developer machine or CI) push new JSON to Blob Storage.

##### Architectural patterns and principles
- Component-based UI decomposition
- Separation of concerns: visual components vs. data hook vs. utility functions
- File-based routing (TanStack Router)
- Static data hosting in cloud blob storage (no backend server)
- Build-time vs. run-time tasks clearly separated (scripts vs. SPA code)

##### Detail level
- Logical module in /src (components, hooks, utils, routes).
- External dependencies (Plotly, Tailwind, shadcn/ui) as labels on the UI layer.
- Environment variables (.env.local → BLOB_READ_WRITE_TOKEN) near the Scripts/Blob Storage connection.
- Document build commands (bun run build, bun run dev) and their outputs (dist folder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers as vertical
    Browser["Browser"]:::frontend
    Browser -->|"GET index.html"| CDN["Vercel CDN"]:::infra
    CDN -->|"Serves"| IndexHTML["index.html"]:::infra
    click IndexHTML "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/index.html"

    IndexHTML -->|"Bootstraps"| MainTS["src/main.tsx"]:::frontend
    click MainTS "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/main.tsx"

    subgraph "React SPA" 
        direction TB
        Router["Route Setup\n(src/routeTree.gen.ts)"]:::frontend
        click Router "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/routeTree.gen.ts"

        subgraph "Layouts & Pages"
            direction TB
            RootLayout["__root.tsx"]:::frontend
            click RootLayout "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/routes/__root.tsx"
            DashboardRoute["index.tsx"]:::frontend
            click DashboardRoute "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/routes/index.tsx"
        end

        subgraph "UI Components"
            direction TB
            DashboardPage["Dashboard.tsx"]:::frontend
            click DashboardPage "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/Dashboard.tsx"
            Controls["DashboardControls.tsx"]:::frontend
            click Controls "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/DashboardControls.tsx"
            BubbleChartWrapper["BubbleChart.tsx"]:::frontend
            click BubbleChartWrapper "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/BubbleChart.tsx"
            PlotlyBubble["PlotlyBubbleChart.tsx"]:::frontend
            click PlotlyBubble "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/PlotlyBubbleChart.tsx"
            PriceDiff["PriceDifferenceChart.tsx"]:::frontend
            click PriceDiff "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/PriceDifferenceChart.tsx"
            Spinner["LoadingSpinner.tsx"]:::frontend
            click Spinner "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/LoadingSpinner.tsx"
            DatePicker["date-picker.tsx"]:::frontend
            click DatePicker "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/date-picker.tsx"
            ThemeProvider["theme-provider.tsx"]:::frontend
            click ThemeProvider "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/theme-provider.tsx"
            ThemeSwitcher["theme-switcher.tsx"]:::frontend
            click ThemeSwitcher "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/components/theme-switcher.tsx"
            UIPrimitives["ui/ (shadcn/ui)"]:::frontend
            click UIPrimitives "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/tree/master/src/components/ui"
        end

        subgraph "Data Layer"
            direction TB
            Hook["useDashboardData.ts"]:::data
            click Hook "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/hooks/useDashboardData.ts"
            LoaderUtil["dataLoader.ts"]:::data
            click LoaderUtil "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/utils/dataLoader.ts"
            Utils["utils.ts"]:::data
            click Utils "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/lib/utils.ts"
            Types["bubbleData.ts"]:::data
            click Types "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/types/bubbleData.ts"
        end

        subgraph "Styles"
            direction TB
            GlobalCSS["styles.css"]:::frontend
            click GlobalCSS "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/styles.css"
            PlotlyCSS["plotly-chart.css"]:::frontend
            click PlotlyCSS "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/styles/plotly-chart.css"
            TooltipCSS["tooltip.css"]:::frontend
            click TooltipCSS "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/src/styles/tooltip.css"
        end

        MainTS --> Router
        Router --> RootLayout
        RootLayout --> DashboardRoute
        DashboardRoute --> DashboardPage
        DashboardPage --> Controls
        DashboardPage --> Hook
        Hook --> LoaderUtil
        LoaderUtil --> Types
        Hook -->|"fetches JSON"| BlobStorage
        DashboardPage --> BubbleChartWrapper
        BubbleChartWrapper --> PlotlyBubble
        BubbleChartWrapper --> PriceDiff
        DashboardPage --> Spinner
        Controls --> DatePicker
        DashboardPage --> ThemeProvider
        ThemeProvider --> ThemeSwitcher
        ThemeProvider --> UIPrimitives
        DashboardPage --> GlobalCSS
        DashboardPage --> PlotlyCSS
        DashboardPage --> TooltipCSS
    end

    subgraph "Cloud Data Storage" 
        direction TB
        BlobStorage["Vercel Blob Storage\n(JSON files)"]:::data
        AzureIcon[(Cylinder)]:::data
    end

    subgraph "Data Management Scripts" 
        direction TB
        Upload["upload-to-blob.ts"]:::data
        click Upload "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/scripts/upload-to-blob.ts"
        GetURLs["get-blob-urls.ts"]:::data
        click GetURLs "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/scripts/get-blob-urls.ts"
        UpdateURLs["update-blob-urls.ts"]:::data
        click UpdateURLs "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/scripts/update-blob-urls.ts"
        TestFetch["test-blob-fetch.ts"]:::data
        click TestFetch "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/scripts/test-blob-fetch.ts"
        Env[".env.local"]:::data
    end

    subgraph "Build & Deployment" 
        direction TB
        PackageJSON["package.json"]:::infra
        click PackageJSON "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/package.json"
        TSConfig["tsconfig.json"]:::infra
        click TSConfig "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/tsconfig.json"
        ViteConfig["vite.config.ts"]:::infra
        click ViteConfig "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/vite.config.ts"
        Biome["biome.json"]:::infra
        click Biome "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/biome.json"
        VercelConfig["vercel.json"]:::infra
        click VercelConfig "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/vercel.json"
        BunLock["bun.lock"]:::infra
        click BunLock "https://github.com/cooper-kerr/financial-bubble-detection-dashboard/blob/master/bun.lock"
        Dist["/dist (build output)"]:::infra
    end

    subgraph "CI/CD Pipeline"
        direction TB
        VercelCI["Vercel Deployment"]:::infra
        VercelCI --> CDN
    end

    %% Relationships
    Upload -->|"PUT JSON"| BlobStorage
    GetURLs -->|"list blobs"| BlobStorage
    UpdateURLs --> BlobStorage
    TestFetch --> BlobStorage
    ViteConfig --> MainTS
    BunLock -->|"npm scripts"| PackageJSON
    PackageJSON --> TSConfig
    PackageJSON --> Biome
    PackageJSON --> VercelConfig
    PackageJSON --> ViteConfig
    TSConfig --> MainTS
    BunLock -->|"dev/build"| Dist
    Dist --> CDN

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef data fill:#E6F4EA,stroke:#28a745,color:#28a745;
    classDef infra fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
```
