# FCC Experimental License Dashboard — User Guide

## Overview

The ELS Dashboard provides a visual overview of FCC Experimental License applications. It loads data from either a pre-built `data.js` file (generated by `build-datajs.ps1`) or from a CSV drag-and-drop import. The dashboard organizes applications across multiple tabs, each focused on a different aspect of license management.

## Getting Started

### Loading Data

**Option A: Pre-built data.js (recommended)**

1. Place your `data*.csv` and `objections*.csv` exports in the same folder as the dashboard.
2. Run `build-datajs.ps1` in PowerShell. It picks the newest CSV files automatically.
3. Open `index.html` in a browser. The dashboard loads instantly from `data.js`.

**Option B: CSV drag-and-drop**

1. Open `index.html` without a `data.js` file present.
2. The CSV overlay appears — drag your export file onto it or click to browse.
3. Once loaded, click **Save data.js** to generate a `data.js` for faster future loads.

### Rebuilding Data

Run `build-datajs.ps1` whenever you receive a new CSV export. The script:
- Skips the rebuild if `data.js` is already newer than the CSV.
- Groups rows by file number + callsign into application objects.
- Nests frequencies under their associated locations (fixed and mobile).
- Builds related-application links (same applicant, callsign, or original file number).
- Merges objection data from `objections*.csv`.
- Deletes the CSV files after a successful build.

## Dashboard Tabs

### Overview

The default tab showing KPIs, charts, and a map.

**KPIs (top cards):**
- Total pending, broken down by Submitted / Assigned / Referred
- New and completed this period (week/month/quarter — selectable)
- Median pending age, open referrals, oldest application, grant rate
- Age distribution strip showing how pending applications distribute across aging buckets

**Charts:**
- **Over Time**: Received (bars), completed (line), total pending (line) across the date range
- **Status Breakdown**: Doughnut showing the split across all statuses
- **Aging**: Horizontal bar showing pending applications by age bucket (0–30d, 30–60d, etc.)

**Map:**
- Fixed locations (blue markers) and mobile locations (orange markers) on a Leaflet map
- Click a marker to see the application, applicant, and authorized frequencies at that location
- Use the layer control to toggle fixed/mobile visibility

### Filters (sidebar)

Visible on the Overview and Analysis tabs. All filters apply cumulatively:
- **Date range**: Filters to applications whose pending window overlaps the range
- **Status checkboxes**: Show only selected statuses
- **Experiment type**: Dropdown filter
- **Applicant search**: Free-text partial match
- **Frequency range**: Show only applications with frequencies overlapping the entered MHz range
- **Charge entities**: Checkbox list of referral entities

Click **Reset** to restore defaults. Filters affect KPIs, charts, and the map in real time.

**Presets**: Save the current filter state by name for quick recall. Up to 20 presets stored in your browser.

### Drilldown

Search for a specific application by name, file number, or callsign. The detail panel shows:
- Application timeline with referral branches (fork-join visualization)
- Referrals table with sortable columns
- External links (application, exhibits, correspondence)
- **Frequencies by location**: Each fixed and mobile location is shown with its authorized frequency ranges — this is the core data relationship the dashboard preserves
- Mini map centered on the application's locations, with popups showing per-location frequencies

### Compare

Compare two related applications to see what changed:
1. Search for the current application.
2. Select a previous/related application from the history dropdown (populated from related applications — same applicant, callsign, or original file number).
3. The comparison shows:
   - **General Information**: Side-by-side field comparison with changed rows highlighted
   - **Fixed/Mobile Locations**: Location-aware diff showing added, removed, and modified locations. Modified locations show which frequencies were added or removed at that specific location.
   - **Referral Entities**: Added/removed/unchanged referral entities
   - **Objections**: Added/removed/unchanged objections

### Analysis

Deeper analytics on the filtered data set:
- **Trend cards**: Top 6 period-over-period changes with sparkline charts
- **Frequency distribution**: Interactive band selector (VLF through EHF) with a line chart showing application density across the spectrum. Use the "Fix Y-axis" toggle to compare bands at the same scale.
- **Experiment type chart**: Horizontal bar chart of application counts by type
- **Processing time**: Median days to decision by experiment type
- **Referral bottleneck**: Median days to close by referral entity, with summary cards for slowest entity, longest open referral, and total open referrals

### Referrals

Filterable table of all referral charges across all applications:
- Filter by entity, open/closed status, and experiment type
- Sortable columns: entity, file number, applicant, dates, age
- Summary cards showing open/closed counts per entity
- CSV export of the filtered referral list

### Renewals

Renewal timeliness analysis (requires `renewal_timeliness` and `renewal_days` columns):
- KPIs: total renewals, timely count, late count, timeliness rate
- Pie chart and days histogram
- Detailed table

### STA (Special Temporary Authority)

Focused view of pending STA applications (file numbers containing "ST"):
- KPIs: total pending, late-filed, with OET / outside OET, operation expired
- Timeline chart showing starts by time bucket (past/today/this week/month/later)
- Pipeline bar showing application states
- Filterable, sortable table with urgency-based sorting
- Toggle between Inside/Outside OET and Timely/Late views

### Friday Report

Weekly summary designed for stakeholders:
- Current-week-in-progress banner
- Week-over-week KPIs with percentage changes
- Pipeline breakdown bar and detail cards
- Referral entity activity table with WoW trends
- 6-week trend chart
- Assigned applications table

Printable via the Print button (uses a print-specific layout).

### Transfers & Assignments

Lists applications with "TU" (transfer) or "AU" (assignment) in their file number:
- Grouped by applicant with expandable panels
- Separated into Pending and Completed sections
- Click a row to jump to the Drilldown tab for that application

### Objections

Displays objection data merged from `objections*.csv`. Populated by `build-datajs.ps1`.

### Flags

Personal flagging system (stored in browser localStorage):
- Flag any application from the Drilldown detail view
- Add notes to flagged applications
- Flags persist across sessions in the same browser
- Flags tab shows all active flags with remove and note controls

## Keyboard Shortcuts & Tips

- **Period selector**: Choose weekly/monthly/quarterly for the Overview and Analysis tabs
- **CSV export**: Available on Overview (filtered), Referrals, STA, and Friday Report tabs
- **Print**: Overview and Friday Report have dedicated print layouts
- **Diagnostics**: Click "Show Diag" on the Overview tab to see data pipeline diagnostics (column mapping, status distribution, grouping checks)

## Data Model

Each application contains:
- Core fields: file number, callsign, name, status, dates
- **Fixed locations**: Each with lat/lon and an array of authorized frequency ranges
- **Mobile locations**: Each with lat/lon, radius, and an array of authorized frequency ranges
- Charges (referrals): Entity name, open date, close date
- Related applications: Linked by original file number, callsign, or applicant name
- Objections: Merged from a separate CSV

The key design principle: **frequencies are tied to locations**, not stored as a flat list. A frequency range authorized at Location A is distinct from the same range at Location B. The dashboard preserves this relationship throughout — in the drilldown view, comparison diffs, map popups, and CSV exports.
