Skip to content

Commit 39ea8be

Browse files
kilraukilrau
committed
feat: monthlyh details page, failure rates, pair data
1 parent 3f9d9a4 commit 39ea8be

14 files changed

+6623
-5448
lines changed

‎BOLTZ_API_DOCS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,13 @@
1+
# Boltz API Reference (Source of Truth)
2+
3+
Do not maintain endpoint details manually in this repository.
4+
5+
Always use the live Boltz swagger spec:
6+
7+
- https://api.boltz.exchange/swagger-spec.json
8+
9+
If behavior in code and docs diverge, trust the swagger spec and update code accordingly.
10+
111
# Boltz API Documentation
212

313
## Partner Referral Stats Endpoint

‎dashboard-enhancement-plan.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
name: Dashboard Enhancements
3+
overview: Implement per-pair volume graphs, swap failure rates graph, and month detail subpages with pair volume trends and daily breakdown views.
4+
todos:
5+
- id: "1"
6+
content: Update types/index.ts with per-pair volume, trades, and failure rates fields
7+
status: completed
8+
- id: "2"
9+
content: Update boltzApi.ts processStatsData() to extract per-pair and failure rate data from API
10+
status: completed
11+
- id: "3"
12+
content: Create PairVolumeChartCombined.tsx with stacked/grouped chart showing all pairs
13+
status: completed
14+
- id: "4"
15+
content: Create PairVolumeChartSeparate.tsx with individual charts per pair
16+
status: completed
17+
- id: "5"
18+
content: Create FailureRateChart.tsx for swap type failure rates
19+
status: completed
20+
- id: "6"
21+
content: Update Dashboard.tsx to integrate new charts (both pair options for comparison)
22+
status: completed
23+
- id: "7"
24+
content: Update MonthlyTable.tsx to make rows clickable with navigation
25+
status: completed
26+
- id: "8"
27+
content: Create MonthDetailPage.tsx with failure rates, pair volume trends, and daily breakdown placeholder
28+
status: completed
29+
- id: "9"
30+
content: Update App.tsx with new /month/:year/:month route
31+
status: completed
32+
- id: "10"
33+
content: Update i18n.ts with new translation keys
34+
status: completed
35+
isProject: false
36+
---
37+
38+
## Overview
39+
40+
This plan implements three major dashboard enhancements:
41+
42+
1. **Per-pair volume graphs** - Show individual volume for each trading pair (BTC/BTC, L-BTC/BTC, etc.)
43+
2. **Swap failure rates graph** - Display failure rates by swap type (submarine, reverse, chain)
44+
3. **Month detail subpages** - Drill-down view for each month showing detailed metrics
45+
46+
## Current Data Available (Not Currently Used)
47+
48+
The Boltz API `/v2/referral/stats` already provides per-pair breakdowns and failure rates that are currently discarded:
49+
50+
```json
51+
{
52+
"2024": {
53+
"1": {
54+
"volume": {
55+
"total": "1.23456789",
56+
"BTC/BTC": "0.5",
57+
"L-BTC/BTC": "0.73456789"
58+
},
59+
"trades": {
60+
"total": 150,
61+
"BTC/BTC": 75,
62+
"L-BTC/BTC": 75
63+
},
64+
"failureRates": {
65+
"submarine": 0.12,
66+
"reverse": 0.05,
67+
"chain": 0.08
68+
}
69+
}
70+
}
71+
}
72+
```
73+
74+
## Implementation Plan
75+
76+
### Phase 1: Update Data Types and API Processing
77+
78+
**File: `src/types/index.ts`**
79+
80+
- Extend `MonthlyStats` interface to include:
81+
- `pairVolume: Record<string, number>` - Volume per trading pair
82+
- `pairTrades: Record<string, number>` - Trade count per pair
83+
- `failureRates: { submarine: number; reverse: number; chain: number }`
84+
85+
**File: `src/services/boltzApi.ts`**
86+
87+
- Update `processStatsData()` to extract per-pair data from API response
88+
- Extract `failureRates` for each month
89+
- Extract volume/trades per pair (excluding "total" key)
90+
91+
### Phase 2: Per-Pair Volume Graph
92+
93+
**Option A: Single Stacked/Grouped Chart (Recommended First)**
94+
**File: `src/components/PairVolumeChart.tsx` (new)**
95+
96+
- Use Recharts `BarChart` with grouped bars or `AreaChart` with stacked areas
97+
- Display all pairs in one chart with different colors
98+
- Legend to toggle pairs on/off
99+
- Color scheme: Use distinct colors per pair (BTC/BTC = orange, L-BTC/BTC = blue, etc.)
100+
101+
**Option B: Separate Charts (If Option A is too crowded)**
102+
103+
- Create a grid of smaller charts, one per pair
104+
- Show up to 2-3 pairs side by side
105+
- Use tabs or dropdown if there are many pairs
106+
107+
**File: `src/components/Dashboard.tsx`**
108+
109+
- Add the pair volume chart below existing charts
110+
- Consider replacing or supplementing the total volume chart
111+
112+
### Phase 3: Swap Failure Rates Graph
113+
114+
**File: `src/components/FailureRateChart.tsx` (new)**
115+
116+
- Use Recharts `BarChart` or `AreaChart`
117+
- Display three data series: submarine, reverse, chain failure rates
118+
- Y-axis: Percentage (0-100%)
119+
- Color coding: Submarine = #4fadc2, Reverse = #f7931a, Chain = #e74c3c
120+
- Tooltip showing exact percentage per swap type
121+
122+
**File: `src/components/Dashboard.tsx`**
123+
124+
- Add failure rate chart to the chart grid (2-column layout)
125+
- Position alongside other metrics for balanced layout
126+
127+
### Phase 4: Month Detail Subpage
128+
129+
**File: `src/App.tsx`**
130+
131+
- Add new route: `/month/:year/:month`
132+
- Protected route wrapper like existing dashboard
133+
134+
**File: `src/pages/MonthDetailPage.tsx` (new)**
135+
Layout structure:
136+
137+
```
138+
Header (Month/Year, Back button)
139+
├── Summary Cards (Total Volume, Total Swaps, Avg Swap Size)
140+
├── Failure Rates Section
141+
│ ├── Bar chart showing submarine/reverse/chain rates
142+
│ └── Comparison to all-time averages
143+
├── Pair Volume Trends (as selected by user)
144+
│ ├── Line chart comparing pairs over full history
145+
│ └── Highlighted indicator for selected month
146+
├── Volume Per Pair Table
147+
│ ├── Pair name, Volume, Swaps, Avg Size
148+
│ └── Percentage of total for that month
149+
└── Daily Breakdown (as selected by user)
150+
├── Placeholder note: "Daily data not yet available from API"
151+
└── Future enhancement: bar chart of daily volume within month
152+
```
153+
154+
**File: `src/components/MonthlyTable.tsx`**
155+
156+
- Make month rows clickable
157+
- Add hover state indicating clickability
158+
- On click, navigate to `/month/:year/:month`
159+
160+
**Additional Metrics for Month Detail Page**
161+
Based on available data, the following can be displayed:
162+
163+
- Pair distribution pie chart (percentage breakdown)
164+
- Month-over-month growth rate per pair
165+
- Average swap size per pair
166+
- Comparison to historical averages
167+
- Best/worst performing pair
168+
169+
### Phase 5: Internationalization
170+
171+
**File: `src/i18n.ts`**
172+
173+
- Add translations for new UI elements:
174+
- "Volume by Pair", "Swap Failure Rates"
175+
- "Month Details", "Daily Breakdown"
176+
- "Pair", "Submarine", "Reverse", "Chain"
177+
178+
## Mermaid Architecture Diagram
179+
180+
```mermaid
181+
flowchart TD
182+
subgraph DataFlow["Data Flow"]
183+
API["Boltz API\n/v2/referral/stats"]
184+
Process["boltzApi.ts\nprocessStatsData()"]
185+
Types["types/index.ts\nExtended MonthlyStats"]
186+
Store["Dashboard State"]
187+
end
188+
189+
subgraph Components["New Components"]
190+
PairChart["PairVolumeChart.tsx\nStacked/Grouped Chart"]
191+
FailureChart["FailureRateChart.tsx\nBar/Line Chart"]
192+
MonthPage["MonthDetailPage.tsx\nSubpage with Details"]
193+
end
194+
195+
subgraph Integration["Integration Points"]
196+
Dashboard["Dashboard.tsx\nAdd New Charts"]
197+
Table["MonthlyTable.tsx\nClickable Rows"]
198+
Router["App.tsx\nNew Route"]
199+
end
200+
201+
API --> Process
202+
Process --> Types
203+
Types --> Store
204+
Store --> Dashboard
205+
Store --> MonthPage
206+
Dashboard --> PairChart
207+
Dashboard --> FailureChart
208+
Table --> Router
209+
Router --> MonthPage
210+
```
211+
212+
213+
214+
## File Changes Summary
215+
216+
217+
| File | Change Type | Description |
218+
| ------------------------------------- | ----------- | ------------------------------------ |
219+
| `src/types/index.ts` | Modify | Add per-pair and failure rate fields |
220+
| `src/services/boltzApi.ts` | Modify | Extract additional data from API |
221+
| `src/components/PairVolumeChart.tsx` | Create | New chart component for pair volumes |
222+
| `src/components/FailureRateChart.tsx` | Create | New chart for failure rates |
223+
| `src/components/MonthlyTable.tsx` | Modify | Add click navigation |
224+
| `src/components/Dashboard.tsx` | Modify | Integrate new charts |
225+
| `src/pages/MonthDetailPage.tsx` | Create | Month detail subpage |
226+
| `src/App.tsx` | Modify | Add routing for subpage |
227+
| `src/i18n.ts` | Modify | Add new translation keys |
228+
229+
230+
## Open Decision: Pair Volume Display
231+
232+
As requested, I'll implement both options so you can decide:
233+
234+
1. **Option A (Single Chart)**: Stacked area or grouped bar chart showing all pairs together
235+
2. **Option B (Separate Charts)**: Individual mini-charts per pair in a grid layout
236+
237+
Both will be created as separate components (`PairVolumeChartCombined.tsx` and `PairVolumeChartSeparate.tsx`) and you can toggle between them in the Dashboard to see which looks better with your actual data.
238+
239+
## Notes on Daily Breakdown
240+
241+
The Boltz API does not currently provide daily-level granularity. The finest granularity available is monthly. For the "Daily Breakdown" feature, I will:
242+
243+
- Create the UI structure for future daily data
244+
- Display a placeholder message explaining daily data is not yet available
245+
- The component will be ready to integrate once Boltz adds daily granularity to the API
246+

0 commit comments

Comments
 (0)