Relevant source files

The following files were used as context for generating this wiki page: - [src/pages/Dashboard.tsx](https://github.com/wendeus0/albion-market-insights/blob/main/src/pages/Dashboard.tsx) - [src/components/dashboard/StatsCard.tsx](https://github.com/wendeus0/albion-market-insights/blob/main/src/components/dashboard/StatsCard.tsx) - [src/components/dashboard/TopItemsPanel.tsx](https://github.com/wendeus0/albion-market-insights/blob/main/src/components/dashboard/TopItemsPanel.tsx) - [src/pages/Index.tsx](https://github.com/wendeus0/albion-market-insights/blob/main/src/pages/Index.tsx) - [features/cross-city-arbitrage/SPEC.md](https://github.com/wendeus0/albion-market-insights/blob/main/features/cross-city-arbitrage/SPEC.md) - [ANALYSIS_REPORT.md](https://github.com/wendeus0/albion-market-insights/blob/main/ANALYSIS_REPORT.md) - [features/lote-p0-correcoes-criticas/SPEC.md](https://github.com/wendeus0/albion-market-insights/blob/main/features/lote-p0-correcoes-criticas/SPEC.md)

# Market Dashboard View The **Market Dashboard View** serves as the primary analytical hub of the Albion Market Insights application. Its core purpose is to provide real-time visualization of market data across seven major Albion Online cities, including the Black Market. It transforms raw price data into actionable intelligence by focusing on **Cross-City Arbitrage**, allowing users to identify profitable trading routes where items can be bought low in one city and sold high in another. The view is architected to handle data synchronization every 15 minutes, ensuring users are viewing fresh market statistics. It incorporates high-level metrics through specialized status cards, a prioritized list of top arbitrage opportunities, and a comprehensive data table for granular analysis. Sources: [src/pages/Dashboard.tsx:43-51](), [README.md:5-7](), [features/cross-city-arbitrage/SPEC.md:33-36]() ## Architecture and Data Flow The Dashboard utilizes a specialized hook-based architecture to manage server state and local data transformations. It primarily consumes data via `useMarketItems` and `useLastUpdateTime` hooks, which interact with the `MarketService` layer. ### Data Synchronization Flow The following diagram illustrates how market data flows from the external API through the service layer into the Dashboard components. ```mermaid graph TD API[Albion Data Project API] --> MS[MarketService/ApiMarketService] MS --> UMI[useMarketItems Hook] UMI --> DB[Dashboard Component] DB --> BCA[buildCrossCityArbitrage Logic] BCA --> AT[ArbitrageTable] BCA --> TAP[TopArbitragePanel] DB --> SC[StatsCards] ``` The dashboard logic processes raw item arrays into arbitrage opportunities using the `buildCrossCityArbitrage` utility, which calculates net profit after a fixed market tax. Sources: [src/pages/Dashboard.tsx:32-41](), [ANALYSIS_REPORT.md:29-41](), [features/cross-city-arbitrage/SPEC.md:38-42]() ### Key Components | Component | Responsibility | Source File | | :--- | :--- | :--- | | `StatsCard` | Displays high-level metrics like Total Items, Avg. ROI, and Last Update time. | [src/components/dashboard/StatsCard.tsx]() | | `TopArbitragePanel` | Shows a curated list of the top 5 arbitrage opportunities by profit percentage. | [src/components/dashboard/TopItemsPanel.tsx]() | | `ArbitrageTable` | Provides a detailed, sortable list of all valid cross-city routes. | [src/pages/Dashboard.tsx:122-124]() | | `DataSourceBadge` | Indicates whether the current data is from the Real API, Mock, or is Degraded. | [features/lote-p0-correcoes-criticas/SPEC.md:16-20]() | | `DegradedBanner` | Alerts the user if the API is failing and the dashboard is in a degraded state. | [features/lote-p0-correcoes-criticas/SPEC.md:26-30]() | ## Arbitrage Logic and Metrics The dashboard focuses on **Cross-City Arbitrage** rather than local price spreads. This logic aggregates prices for the same item across different cities to find the optimal buy/sell pair. ### Profit Calculation The system applies a conservative fixed market tax of **6.5%** to all sell prices to determine the net profit. ```mermaid flowchart TD A[Raw Market Data] --> B{Valid Item?} B -- Yes --> C[Group by Item ID & Quality] C --> D[Identify Min Sell Price - Buy City] C --> E[Identify Max Buy Price - Sell City] D & E --> F[Calculate Net Profit] F --> G[Net Profit = SellPrice * 0.935 - BuyPrice] G --> H[Rank by Net ROI %] ``` *Note: Opportunities with a net profit less than or equal to zero are excluded from the view.* Sources: [features/cross-city-arbitrage/SPEC.md:52-70](), [src/pages/Dashboard.tsx:43-47]() ### Status and Freshness Data freshness is tracked through a relative timestamp system. The dashboard calculates labels such as "Updated just now" or "Updated 5 min ago" to provide immediate feedback on the relevance of the displayed prices. ```typescript // Logic from src/pages/Dashboard.tsx:13-28 function getRelativeUpdateLabel(lastUpdate: string | null, isRefreshing: boolean): string { if (isRefreshing) return "Syncing..."; if (!lastUpdate) return "Awaiting first sync"; const elapsedMs = Date.now() - new Date(lastUpdate).getTime(); const elapsedMinutes = Math.floor(elapsedMs / 60_000); if (elapsedMinutes < 60) return `Updated ${elapsedMinutes} min ago`; // ... } ``` Sources: [src/pages/Dashboard.tsx:13-30](), [features/lote-p0-correcoes-criticas/SPEC.md:39-44]() ## Layout and UI Structure The Market Dashboard View is divided into three primary sections designed for a top-down information hierarchy: 1. **Header and Source Indicators:** Displays the page title alongside the `DataSourceBadge` and a live sync status label. 2. **Statistics Grid:** A four-column layout showing "Total Items", "Cities" (7 covering major hubs and Black Market), "Avg. ROI", and the specific "Last Update" time. 3. **Arbitrage Analysis Area:** A split-view layout. On large screens, the `TopArbitragePanel` occupies a sidebar (1/4 width) while the `ArbitrageTable` occupies the main content area (3/4 width). ### Dashboard Component Skeleton ```tsx // Structure from src/pages/Dashboard.tsx:64-131 return (

{/* Title and Sync Status */}

{/* Additional Stats */}

); ``` Sources: [src/pages/Dashboard.tsx:64-131](), [src/pages/Index.tsx:136-150]() ## Summary of Operational Constants The Dashboard behavior is governed by several operational constants defined within the project: | Constant | Value | Description | | :--- | :--- | :--- | | `DATA_FRESHNESS_MS` | 15 Minutes | The interval for automatic data refetching. | | `MARKET_TAX_RATE` | 6.5% | Fixed tax applied to sell prices for profit calculation. | | `REFRESH_COOLDOWN` | 5 Minutes | Restriction on manual user refresh attempts. | | `CITIES_COUNT` | 7 | Includes Caerleon, Bridgewatch, Fort Sterling, Lymhurst, Martlock, Thetford, and Black Market. | Sources: [src/pages/Dashboard.tsx:11](), [features/cross-city-arbitrage/SPEC.md:44-46](), [features/lote-p0-correcoes-criticas/SPEC.md:57-61](), [src/pages/About.tsx:125-131]() The Market Dashboard View effectively centralizes complex market dynamics into a simplified trading interface. By prioritizing cross-city arbitrage and maintaining strict data freshness indicators, it ensures that users can make informed trading decisions based on net-profitability rather than misleading local price spreads.