# tushallohar/cryptoverse architecture

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

- Interactive diagram: https://gitdiagram.com/tushallohar/cryptoverse
- Repository: https://github.com/tushallohar/cryptoverse

## Overview

This repository is a client-side React application built with Vite. Architecturally, it is a single-page crypto market/portfolio dashboard with a thin serverless API layer for proxying external services. The main runtime is the browser; the backend surface is limited to Vercel-hosted functions in `api/`.

The application shell is centered around `src/main.jsx`, `src/app/routes.jsx`, and `src/layout/*`. `AppLayout`, `Header`, and `TickerBar` provide the persistent frame, while route-level screens in `src/pages/` and `src/features/` fill the main content area. This suggests a shared chrome with many specialized analytics views rather than separate apps.

Routing is a key organizing boundary. `src/app/routes.jsx` maps a large set of pages such as market overview, coin detail, alerts, watchlist, portfolio, AI chat, arbitrage, backtesting, screener, heatmap, on-chain, and whale alerts. `NotFoundPage` handles unmatched routes, so the navigation layer is intentionally broad and feature-driven.

The app’s main business logic is split across feature components and reusable hooks. `src/features/` contains higher-level screens like `MarketPage` and `CoinDetailPage`, while `src/hooks/` contains the data-fetching and derived-state logic for live prices, market data, charting, alerts, page titles, and coin details. This keeps UI components relatively thin and pushes API and transformation logic into reusable modules.

External market data appears to come through utility clients in `src/utils/`, especially `marketAPI.jsx` and `apiClient.jsx`. Those utilities likely consume CoinGecko data directly or via the local proxy endpoints. The presence of `api/coingecko-proxy.js` indicates the repository uses a serverless proxy boundary to avoid browser-side CORS issues and to centralize outbound API access.

AI functionality is isolated as a separate subsystem. `src/pages/AiChatPage.jsx` talks to `src/utils/geminiAPI.jsx`, which in turn is backed by `api/gemini-proxy.js`. That creates a clean separation between the browser UI and the Gemini service, with the proxy acting as the trust boundary for any API keys or request shaping.

Client-side state is divided into shared context and persisted stores. `src/context/ThemeContext.jsx` and `src/context/CurrencyContext.jsx` manage app-wide preferences, while `src/store/alertsStore.jsx`, `watchlistStore.jsx`, and `portfolioStore.jsx` hold user-managed domain state. This points to a hybrid state model: React context for global settings and dedicated stores for domain data that likely needs persistence or cross-page access.

There is also a local persistence layer for chart data. `src/utils/indexedDbCharts.jsx` suggests chart history or time-series caches are stored in IndexedDB, which reduces repeat fetches and supports richer chart interactions. This is an important architectural boundary because it moves part of the data layer into the browser itself.

Visualization is a major subsystem. `src/components/CandlestickChart.jsx`, the various market pages, and utility hooks like `useChart` indicate charting and technical-analysis-style views are first-class. `src/components/ui/Toast.jsx` and `src/components/ErrorBoundary.jsx` provide shared UX infrastructure for transient feedback and fault isolation.

Styling and build tooling are standard but relevant to the architecture. The repo uses Tailwind CSS (`tailwind.config.js`, `postcss.config.js`) and Vite (`vite.config.js`) for fast SPA builds and development HMR. `eslint.config.js` defines code quality boundaries, while `vercel.json` ties the app to Vercel deployment and serverless function hosting.

Overall data flow is: user navigates a route, a page or feature component invokes a hook, the hook calls a utility/API client, the request may go through a local serverless proxy to an external service, and the result is normalized into shared state or rendered directly. User preferences and app-specific data then flow back through contexts/stores and, where needed, browser persistence such as IndexedDB.

Main entry points: [`src/app/routes.jsx`](https://github.com/tushallohar/cryptoverse/blob/main/src/app/routes.jsx) (Routes), [`src/hooks`](https://github.com/tushallohar/cryptoverse/tree/main/src/hooks) (Data Hooks), [`src/layout/AppLayout.jsx`](https://github.com/tushallohar/cryptoverse/blob/main/src/layout/AppLayout.jsx) (App Shell), [`src/pages`](https://github.com/tushallohar/cryptoverse/tree/main/src/pages) (Analytics Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_routes["Routes<br/>route map<br/>[routes.jsx]"]
  node_layout["App Shell<br/>layout shell<br/>[AppLayout.jsx]"]
  node_header["Header<br/>chrome<br/>[Header.jsx]"]
  node_ticker["Ticker Bar<br/>market chrome<br/>[TickerBar.jsx]"]
  node_market["Market View<br/>feature screen<br/>[MarketPage.jsx]"]
  node_coin["Coin Detail<br/>feature screen<br/>[CoinDetailPage.jsx]"]
  node_analytics["Analytics Pages<br/>route screens"]
  node_ai["AI Chat<br/>assistant screen<br/>[AiChatPage.jsx]"]
  node_chart(("Candlestick Chart<br/>chart component"))
  node_feedback["Feedback UI<br/>shared ui<br/>[ErrorBoundary.jsx]"]
end

subgraph group_data["State & data"]
  node_contexts["App Contexts<br/>global prefs"]
  node_stores["Domain Stores<br/>client state"]
  node_hooks["Data Hooks<br/>react hooks"]
  node_api["API Clients<br/>service clients"]
  node_cache[("Chart Cache<br/>indexeddb")]
  node_marketapi["Market API<br/>market client<br/>[marketAPI.jsx]"]
  node_geminiapi["Gemini API<br/>ai client<br/>[geminiAPI.jsx]"]
end

subgraph group_serverless["Serverless API"]
  node_coingecko["CoinGecko Proxy<br/>serverless function<br/>[coingecko-proxy.js]"]
  node_geminiproxy["Gemini Proxy<br/>serverless function<br/>[gemini-proxy.js]"]
end

node_routes -->|"mounts"| node_layout
node_layout -->|"contains"| node_header
node_layout -->|"contains"| node_ticker
node_routes -->|"renders"| node_market
node_routes -->|"renders"| node_coin
node_routes -->|"renders"| node_analytics
node_routes -->|"renders"| node_ai
node_market -->|"uses"| node_hooks
node_coin -->|"uses"| node_hooks
node_market -->|"shows"| node_chart
node_coin -->|"shows"| node_chart
node_analytics -->|"shares"| node_stores
node_analytics -->|"uses"| node_hooks
node_ai -->|"calls"| node_geminiapi
node_hooks -->|"delegates"| node_api
node_api -->|"includes"| node_marketapi
node_api -->|"includes"| node_geminiapi
node_marketapi -->|"proxies through"| node_coingecko
node_geminiapi -->|"proxies through"| node_geminiproxy
node_hooks -->|"persists"| node_cache
node_contexts -->|"provides"| node_layout
node_stores -->|"feeds"| node_analytics
node_feedback -->|"guards"| node_routes

click node_routes "https://github.com/tushallohar/cryptoverse/blob/main/src/app/routes.jsx"
click node_layout "https://github.com/tushallohar/cryptoverse/blob/main/src/layout/AppLayout.jsx"
click node_header "https://github.com/tushallohar/cryptoverse/blob/main/src/layout/Header.jsx"
click node_ticker "https://github.com/tushallohar/cryptoverse/blob/main/src/layout/TickerBar.jsx"
click node_market "https://github.com/tushallohar/cryptoverse/blob/main/src/features/MarketPage.jsx"
click node_coin "https://github.com/tushallohar/cryptoverse/blob/main/src/features/CoinDetailPage.jsx"
click node_analytics "https://github.com/tushallohar/cryptoverse/tree/main/src/pages"
click node_ai "https://github.com/tushallohar/cryptoverse/blob/main/src/pages/AiChatPage.jsx"
click node_chart "https://github.com/tushallohar/cryptoverse/blob/main/src/components/CandlestickChart.jsx"
click node_feedback "https://github.com/tushallohar/cryptoverse/blob/main/src/components/ErrorBoundary.jsx"
click node_contexts "https://github.com/tushallohar/cryptoverse/tree/main/src/context"
click node_stores "https://github.com/tushallohar/cryptoverse/tree/main/src/store"
click node_hooks "https://github.com/tushallohar/cryptoverse/tree/main/src/hooks"
click node_api "https://github.com/tushallohar/cryptoverse/tree/main/src/utils"
click node_cache "https://github.com/tushallohar/cryptoverse/blob/main/src/utils/indexedDbCharts.jsx"
click node_marketapi "https://github.com/tushallohar/cryptoverse/blob/main/src/utils/marketAPI.jsx"
click node_geminiapi "https://github.com/tushallohar/cryptoverse/blob/main/src/utils/geminiAPI.jsx"
click node_coingecko "https://github.com/tushallohar/cryptoverse/blob/main/api/coingecko-proxy.js"
click node_geminiproxy "https://github.com/tushallohar/cryptoverse/blob/main/api/gemini-proxy.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_layout,node_header,node_ticker,node_market,node_coin,node_analytics,node_ai,node_chart,node_feedback toneBlue
class node_contexts,node_stores,node_hooks,node_api,node_cache,node_marketapi,node_geminiapi toneAmber
class node_coingecko,node_geminiproxy toneMint
```

## Components

### Browser app

Client-side React shell, routes, screens, and shared presentation components.

- [Routes](https://github.com/tushallohar/cryptoverse/blob/main/src/app/routes.jsx): route map · Top-level route registry and navigation boundaries. · `src/app/routes.jsx`
- [App Shell](https://github.com/tushallohar/cryptoverse/blob/main/src/layout/AppLayout.jsx): layout shell · Persistent frame for the SPA content area. · `src/layout/AppLayout.jsx`
- [Header](https://github.com/tushallohar/cryptoverse/blob/main/src/layout/Header.jsx): chrome · Top navigation and app-level controls. · `src/layout/Header.jsx`
- [Ticker Bar](https://github.com/tushallohar/cryptoverse/blob/main/src/layout/TickerBar.jsx): market chrome · Persistent market ticker displayed across screens. · `src/layout/TickerBar.jsx`
- [Market View](https://github.com/tushallohar/cryptoverse/blob/main/src/features/MarketPage.jsx): feature screen · Primary market overview surface. · `src/features/MarketPage.jsx`
- [Coin Detail](https://github.com/tushallohar/cryptoverse/blob/main/src/features/CoinDetailPage.jsx): feature screen · Per-asset detail and analytics surface. · `src/features/CoinDetailPage.jsx`
- [Analytics Pages](https://github.com/tushallohar/cryptoverse/tree/main/src/pages): route screens · Specialized market tools and dashboards such as watchlist, portfolio, screener, heatmap, on-chain, and backtesting. · `src/pages`
- [AI Chat](https://github.com/tushallohar/cryptoverse/blob/main/src/pages/AiChatPage.jsx): assistant screen · Browser UI for conversational AI features. · `src/pages/AiChatPage.jsx`
- [Candlestick Chart](https://github.com/tushallohar/cryptoverse/blob/main/src/components/CandlestickChart.jsx): chart component · Primary visualization for price history and technical analysis. · `src/components/CandlestickChart.jsx`
- [Feedback UI](https://github.com/tushallohar/cryptoverse/blob/main/src/components/ErrorBoundary.jsx): shared ui · Reusable error and toast presentation components. · `src/components/ErrorBoundary.jsx`

### State & data

Hooks, stores, context, and utilities that drive fetching and client state.

- [App Contexts](https://github.com/tushallohar/cryptoverse/tree/main/src/context): global prefs · Theme and currency preference providers. · `src/context`
- [Domain Stores](https://github.com/tushallohar/cryptoverse/tree/main/src/store): client state · Persistent watchlist, alerts, and portfolio state. · `src/store`
- [Data Hooks](https://github.com/tushallohar/cryptoverse/tree/main/src/hooks): react hooks · Shared fetching and derived-state hooks for live prices, market data, charts, alerts, and titles. · `src/hooks`
- [API Clients](https://github.com/tushallohar/cryptoverse/tree/main/src/utils): service clients · Browser-side clients that normalize market and AI service calls. · `src/utils`
- [Chart Cache](https://github.com/tushallohar/cryptoverse/blob/main/src/utils/indexedDbCharts.jsx): indexeddb · Local browser persistence for chart history and time-series reuse. · `src/utils/indexedDbCharts.jsx`
- [Market API](https://github.com/tushallohar/cryptoverse/blob/main/src/utils/marketAPI.jsx): market client · External market-data access layer. · `src/utils/marketAPI.jsx`
- [Gemini API](https://github.com/tushallohar/cryptoverse/blob/main/src/utils/geminiAPI.jsx): ai client · Client wrapper for AI chat requests. · `src/utils/geminiAPI.jsx`

### Serverless API

Vercel-hosted proxy functions for external services.

- [CoinGecko Proxy](https://github.com/tushallohar/cryptoverse/blob/main/api/coingecko-proxy.js): serverless function · Proxy endpoint for external market-data requests. · `api/coingecko-proxy.js`
- [Gemini Proxy](https://github.com/tushallohar/cryptoverse/blob/main/api/gemini-proxy.js): serverless function · Proxy endpoint for AI service requests. · `api/gemini-proxy.js`

## Connections

- Routes → App Shell: mounts · Routes are rendered inside the persistent app shell.
- App Shell → Header: contains · Shell includes the global header.
- App Shell → Ticker Bar: contains · Shell includes the live ticker bar.
- Routes → Market View: renders · One route target is the market overview feature.
- Routes → Coin Detail: renders · One route target is the coin detail feature.
- Routes → Analytics Pages: renders · Many routes land in specialized analytics pages.
- Routes → AI Chat: renders · AI chat is exposed as its own route.
- Market View → Data Hooks: uses · Market view depends on shared market data hooks.
- Coin Detail → Data Hooks: uses · Coin detail view depends on shared data hooks.
- Market View → Candlestick Chart: shows · Market view uses chart visualization components.
- Coin Detail → Candlestick Chart: shows · Coin detail view uses chart visualization components.
- Analytics Pages → Domain Stores: shares · Analytics surfaces reuse domain state stores where relevant.
- Analytics Pages → Data Hooks: uses · Analytics pages compose shared hooks for derived data.
- AI Chat → Gemini API: calls · AI chat uses the Gemini client wrapper.
- Data Hooks → API Clients: delegates · Hooks delegate transport and normalization to utility clients.
- API Clients → Market API: includes · Market client is the primary external data entry point.
- API Clients → Gemini API: includes · Gemini client is the AI entry point.
- Market API → CoinGecko Proxy: proxies through · Market data requests go through the CoinGecko serverless boundary.
- Gemini API → Gemini Proxy: proxies through · AI requests go through the Gemini serverless boundary.
- Data Hooks → Chart Cache: persists · Chart-related hooks use IndexedDB-backed persistence.
- App Contexts → App Shell: provides · Global preferences are made available through the app shell.
- Domain Stores → Analytics Pages: feeds · Persistent domain state feeds portfolio, watchlist, and alerts pages.
- Feedback UI → Routes: guards · Shared error handling protects route-level rendering.