How cooper-kerr/financial-bubble-detection-dashboard works
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).