Skip to content

Commit 9b3852b

Browse files
jduteaujduteau
committed
Update documentation
1 parent da3026c commit 9b3852b

2 files changed

Lines changed: 204 additions & 26 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 33 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,33 @@
11
# FHL Dashboard AI Coding Instructions
22

33
## Project Overview
4-
This is an Observable Framework dashboard for Fantasy Hockey League (FHL) management. The app displays team standings, player statistics, roster management, and team comparisons through interactive data visualizations.
4+
This is a comprehensive Observable Framework dashboard for Fantasy Hockey League (FHL) management (2025-26 season). The app displays team standings, player statistics, roster management, and team comparisons through interactive data visualizations. Features seven main sections: Team Standings, Team Information, Team Statistics (Players), Team Roster, Overall Stats, Compare Teams, and Stats Visualizations.
55

66
## Architecture & Data Flow
77

88
### Data Pipeline
9-
- **External data collection**: Shell scripts (`fhlgetstats.sh`, `fhlgetplayerinfo.sh`) fetch stats from external sources
10-
- **Data loaders** (`src/data/*.json.js`): Transform CSV files into structured JSON for the framework
11-
- **CSV data sources** (`src/data/*.csv`): Raw data files for teams, players, contracts, rosters by period
12-
- **Components** (`src/components/loadfiles.js`): Shared utilities for data parsing and calculations
9+
- **External data collection**: Shell scripts (`fhlgetstats.sh`, `fhlgetplayerinfo.sh`, `fhlgetplayoffstats.sh`) fetch stats from external sources
10+
- **Data loaders** (`src/data/*.json.js`): Transform CSV files into structured JSON for the framework
11+
- **CSV data sources** (`src/data/static/*.csv`): Raw data files for teams, players, contracts
12+
- **Period-specific data**: `src/data/static/stats/` and `src/data/static/rosters/` contain period-numbered files (P01-P25)
13+
- **Components** (`src/components/loadfiles.js`): Shared utilities for data parsing, stat calculations, and period management
1314

1415
### Key Data Concepts
15-
- **Periods**: FHL operates in numbered periods (P01, P02, etc.) representing scoring periods
16+
- **Periods**: FHL operates in numbered periods (P01, P02, etc.) representing scoring periods. Currently supports 25 periods.
1617
- **Stats calculations**:
1718
- D-Stat: `blocks + takeaways - giveaways + (toi / divisor)` where divisor = 20 for D, 30 for F
1819
- G-Stat: `2*wins + ties + 2*shutouts + 0.15*shots_against - goals_against`
1920
- Toughness: `pim + hits`
20-
- **Position mapping**: Observable uses F/D/G instead of detailed positions like LW/RW/C
21+
- **Position mapping**: Observable uses F/D/G instead of detailed positions like LW/RW/C via `mapPosition()`
22+
- **Age calculations**: Ages calculated as of September 15, 2025 cutoff date via `calculateAge()`
23+
- **Period differentials**: `getStatsForPeriod()` calculates period-to-period stat changes
2124

2225
### File Patterns
23-
- Period-specific player statistics in src/data using stats_p## naming
24-
- Period-specific team rosters in src/data using rosters_p## naming
26+
- Period-specific player statistics: `src/data/static/stats/stats_p##.csv` (P01-P25)
27+
- Period-specific team rosters: `src/data/static/rosters/rosters_p##.csv` (P01-P25)
2528
- Data loaders export structured objects with `availablePeriods`, `teams`, and calculated rankings
29+
- Core utilities in `loadfiles.js`: `statsPeriods`, `rosterPeriods`, `statsData`, `rosterData` arrays
30+
- Available periods dynamically determined: `availablePeriods = [...Object.keys(statsData)]`
2631

2732
## Development Workflow
2833

@@ -31,9 +36,12 @@ This is an Observable Framework dashboard for Fantasy Hockey League (FHL) manage
3136
# Update stats for specific period (e.g., period 5)
3237
./fhlgetstats.sh 05
3338

34-
# Update player information
39+
# Update player information
3540
./fhlgetplayerinfo.sh
3641

42+
# Update playoff statistics
43+
./fhlgetplayoffstats.sh
44+
3745
# Clear data cache and rebuild
3846
npm run clean && npm run dev
3947
```
@@ -51,7 +59,10 @@ npm run deploy # Deploy to Observable Cloud
5159
- Use `readCsvFile()` and `readStatsFile()` from `loadfiles.js` for consistent CSV parsing
5260
- Numeric fields are auto-converted: `CASH`, `Salary`, and all `stats/*` fields
5361
- Position mapping through `mapPosition()`: converts NHL positions to F/D/G
54-
- Age calculation via `calculateAge()` using birth dates
62+
- Age calculation via `calculateAge()` using birth dates with September 15, 2025 cutoff
63+
- Period-specific stats via `getStatsForPeriod()`: calculates period differentials for all fantasy stats
64+
- Data structures: `statsData[period]` and `rosterData[period]` for period-specific access
65+
- Latest data shortcuts: `latestStatsFile` and `latestRosterFile` for current period defaults
5566

5667
### UI Patterns
5768
- **Period selectors**: Use `availablePeriods` array with last period as default
@@ -72,5 +83,14 @@ npm run deploy # Deploy to Observable Cloud
7283

7384
## External Dependencies
7485
- Data updates require external Node.js scripts in separate `FHL-Stat-Scripts` directory
75-
- Uses d3-dsv for CSV parsing, strip-bom for file encoding
76-
- Observable Framework handles build/deployment pipeline
86+
- Uses d3-dsv for CSV parsing, strip-bom for file encoding, d3-time-format for date handling
87+
- Observable Framework handles build/deployment pipeline
88+
- Node.js engine requirement: >=18
89+
- Development dependency: rimraf for cache clearing
90+
91+
## Current Season Details
92+
- **Season**: 2025-26
93+
- **App Title**: "2025-26 FHL Dashboard"
94+
- **Age Cutoff**: September 15, 2025
95+
- **Supported Periods**: 1-25 (P01-P25)
96+
- **Navigation**: 7 main sections with custom page routing in observablehq.config.js

‎README.md‎

Lines changed: 171 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,131 @@
11
# FHL Dashboard
22

3-
This is an [Observable Framework](https://observablehq.com/framework/) app. To install the required dependencies, run:
3+
A comprehensive Fantasy Hockey League (FHL) management dashboard built with [Observable Framework](https://observablehq.com/framework/). This application provides interactive visualizations for team standings, player statistics, roster management, and team comparisons.
44

5-
```
5+
## Quick Start
6+
7+
Install dependencies and start the development server:
8+
9+
```bash
610
npm install
11+
npm run dev
712
```
813

9-
Then, to start the local preview server, run:
14+
Then visit <http://localhost:3000> to preview your app.
15+
16+
## Project Overview
17+
18+
The FHL Dashboard consists of seven main sections:
19+
20+
- **Team Standings** - Division-based standings and overall team rankings
21+
- **Team Information** - Team details, cash, salaries, and roster summaries
22+
- **Team Statistics** (Players) - Individual player performance and fantasy statistics
23+
- **Team Roster** - Period-specific roster management and player assignments
24+
- **Overall Stats** - Cumulative statistics across all periods
25+
- **Compare Teams** - Head-to-head team performance comparison
26+
- **Stats Visualizations** - Interactive charts and graphs
27+
28+
## Project Structure
29+
30+
```
31+
.
32+
├─ src/
33+
│ ├─ components/
34+
│ │ └─ loadfiles.js # shared data utilities and stat calculations
35+
│ ├─ data/
36+
│ │ ├─ *.json.js # data loaders (transform CSV to JSON)
37+
│ │ └─ static/
38+
│ │ ├─ *.csv # raw team/player data
39+
│ │ ├─ stats/ # period-specific stats (stats_p01.csv - stats_p25.csv)
40+
│ │ └─ rosters/ # period-specific rosters (rosters_p01.csv - rosters_p25.csv)
41+
│ ├─ *.md # dashboard pages
42+
│ └─ index.md # home page
43+
├─ fhlgetstats.sh # fetch stats for specific period
44+
├─ fhlgetplayerinfo.sh # update player information
45+
├─ fhlgetplayoffstats.sh # fetch playoff statistics
46+
└─ observablehq.config.js # app configuration and navigation
47+
```
48+
49+
**`src`** - Source root containing all dashboard pages (Markdown files), data loaders, and shared components.
50+
51+
**`src/components/loadfiles.js`** - Core utilities for data parsing, stat calculations (D-Stat, G-Stat, Toughness), position mapping, age calculations, and period management.
52+
53+
**`src/data/`** - Data loaders that transform CSV files into structured JSON, plus static CSV files organized by periods.
54+
55+
**`observablehq.config.js`** - App configuration defining the seven main navigation sections and page routing.
56+
57+
## FHL Data Concepts
58+
59+
### Periods
60+
FHL operates in numbered periods (P01, P02, etc.) representing scoring periods throughout the season. Currently supports periods 1-25.
61+
62+
### Fantasy Statistics
63+
- **D-Stat**: `blocks + takeaways - giveaways + (toi / divisor)` where divisor = 20 for defensemen, 30 for forwards
64+
- **G-Stat**: `2*wins + ties + 2*shutouts + 0.15*shots_against - goals_against`
65+
- **Toughness**: `pim + hits`
66+
67+
### Position Mapping
68+
- NHL positions (C, LW, RW, etc.) are mapped to simplified positions: F (Forward), D (Defense), G (Goalie)
69+
- Age calculations use September 15 cutoff date for the current season
70+
71+
## Data Management
72+
73+
### Updating Stats
74+
```bash
75+
# Update stats for specific period (e.g., period 5)
76+
./fhlgetstats.sh 05
77+
78+
# Update player information
79+
./fhlgetplayerinfo.sh
80+
81+
# Update playoff stats
82+
./fhlgetplayoffstats.sh
1083

84+
# Clear data cache and rebuild
85+
npm run clean && npm run dev
1186
```
87+
88+
### Data Dependencies
89+
- Requires external Node.js scripts in separate `FHL-Stat-Scripts` directory
90+
- Stats are fetched from external sources and processed into CSV format
91+
- Data loaders transform CSV files into structured JSON for the framework
92+
93+
## Command Reference
94+
95+
| Command | Description |
96+
| -------------------- | -------------------------------------------------------- |
97+
| `npm install` | Install or reinstall dependencies |
98+
| `npm run dev` | Start local preview server |
99+
| `npm run build` | Build your static site, generating `./dist` |
100+
| `npm run deploy` | Deploy your app to Observable Cloud |
101+
| `npm run clean` | Clear the local data loader cache |
102+
| `npm run observable` | Run commands like `observable help` |
103+
| `./fhlgetstats.sh ##`| Update stats for specific period number |
104+
| `./fhlgetplayerinfo.sh` | Update player information |
105+
| `./fhlgetplayoffstats.sh` | Update playoff statistics |
106+
107+
## Technical Stack
108+
109+
- **Framework**: Observable Framework
110+
- **Data Processing**: d3-dsv for CSV parsing, strip-bom for file encoding
111+
- **Visualization**: Built-in Observable Framework components and D3.js
112+
- **Deployment**: Observable Cloud
113+
114+
For more information about Observable Framework, see <https://observablehq.com/framework/getting-started>.# FHL Dashboard
115+
116+
A comprehensive Fantasy Hockey League (FHL) management dashboard built with [Observable Framework](https://observablehq.com/framework/). This application provides interactive visualizations for team standings, player statistics, roster management, and team comparisons.
117+
118+
## Quick Start
119+
120+
Install dependencies and start the development server:
121+
122+
```bash
123+
npm install
12124
npm run dev
13125
```
14126

15127
Then visit <http://localhost:3000> to preview your app.
16128

17-
For more, see <https://observablehq.com/framework/getting-started>.
18-
19129
## Project structure
20130

21131
A typical Framework project looks like this:
@@ -47,13 +157,61 @@ A typical Framework project looks like this:
47157

48158
**`observablehq.config.js`** - This is the [app configuration](https://observablehq.com/framework/config) file, such as the pages and sections in the sidebar navigation, and the app’s title.
49159

50-
## Command reference
160+
## FHL Data Concepts
161+
162+
### Periods
163+
FHL operates in numbered periods (P01, P02, etc.) representing scoring periods throughout the season. Currently supports periods 1-25.
164+
165+
### Fantasy Statistics
166+
- **D-Stat**: `blocks + takeaways - giveaways + (toi / divisor)` where divisor = 20 for defensemen, 30 for forwards
167+
- **G-Stat**: `2*wins + ties + 2*shutouts + 0.15*shots_against - goals_against`
168+
- **Toughness**: `pim + hits`
169+
170+
### Position Mapping
171+
- NHL positions (C, LW, RW, etc.) are mapped to simplified positions: F (Forward), D (Defense), G (Goalie)
172+
- Age calculations use September 15 cutoff date for the current season
173+
174+
## Data Management
175+
176+
### Updating Stats
177+
```bash
178+
# Update stats for specific period (e.g., period 5)
179+
./fhlgetstats.sh 05
180+
181+
# Update player information
182+
./fhlgetplayerinfo.sh
183+
184+
# Update playoff stats
185+
./fhlgetplayoffstats.sh
186+
187+
# Clear data cache and rebuild
188+
npm run clean && npm run dev
189+
```
190+
191+
### Data Dependencies
192+
- Requires external Node.js scripts in separate `FHL-Stat-Scripts` directory
193+
- Stats are fetched from external sources and processed into CSV format
194+
- Data loaders transform CSV files into structured JSON for the framework
195+
196+
## Command Reference
51197

52-
| Command | Description |
53-
| ----------------- | -------------------------------------------------------- |
54-
| `npm install` | Install or reinstall dependencies |
198+
| Command | Description |
199+
| -------------------- | -------------------------------------------------------- |
200+
| `npm install` | Install or reinstall dependencies |
55201
| `npm run dev` | Start local preview server |
56-
| `npm run build` | Build your static site, generating `./dist` |
57-
| `npm run deploy` | Deploy your app to Observable |
58-
| `npm run clean` | Clear the local data loader cache |
59-
| `npm run observable` | Run commands like `observable help` |
202+
| `npm run build` | Build your static site, generating `./dist` |
203+
| `npm run deploy` | Deploy your app to Observable Cloud |
204+
| `npm run clean` | Clear the local data loader cache |
205+
| `npm run observable` | Run commands like `observable help` |
206+
| `./fhlgetstats.sh ##`| Update stats for specific period number |
207+
| `./fhlgetplayerinfo.sh` | Update player information |
208+
| `./fhlgetplayoffstats.sh` | Update playoff statistics |
209+
210+
## Technical Stack
211+
212+
- **Framework**: Observable Framework
213+
- **Data Processing**: d3-dsv for CSV parsing, strip-bom for file encoding
214+
- **Visualization**: Built-in Observable Framework components and D3.js
215+
- **Deployment**: Observable Cloud
216+
217+
For more information about Observable Framework, see <https://observablehq.com/framework/getting-started>.

0 commit comments

Comments
 (0)