chore: Modularize frontend architecture and remove ORCA code (#33)

## Summary

This PR refactors the contributor network visualization from a 3,400+
line monolithic `index.js` into a modular, maintainable architecture
with 32 focused ES6 modules. The main entry point has been reduced by
**~57%** (from 3,400+ lines to 1,505 lines), with complex logic
extracted into dedicated, testable modules.

This refactoring also includes significant code cleanup, removing
**~500+ lines of ORCA-specific code** that was inherited from the
original visualization but not used in our implementation. This includes
ORCA data loading, ORCA-specific positioning logic, dual ring
visualization, and highlight backgrounds.

<sup>1</sup> *Note: Vite was initially added during development to test
bundling, but we ultimately decided against it to reduce complexity and
use native ES modules instead.*

### Code Cleanup: ORCA-Specific Code Removal

**Removed:**
- ORCA data loading and processing logic
- ORCA-specific positioning (`RADIUS_CONTRIBUTOR_NON_ORCA`,
`ORCA_PRESENT` flag)
- Dual ring visualization (ORCA vs non-ORCA contributors)
- ORCA highlight backgrounds and opacity reduction logic
- ORCA-specific tooltip content
- `orca_received` and `orca_impacted` data properties
- Remaining contributors ring drawing (not used in our visualization)

**Renamed for Clarity:**
- `ORCA_RING_WIDTH` → `CONTRIBUTOR_RING_WIDTH` (generic contributor
ring)
- `createORCAVisual` → `createContributorNetworkVisual`
- `debug-orca` flag → `debug-contributor-network`

### Architecture Changes

#### 1. **Data Preparation Module** (`src/js/data/prepare.js`)
- Extracted `prepareData()` function (~515 lines → 673 lines with
documentation)
- Handles all data transformation, normalization, and node creation
- Returns structured data object instead of mutating global state
- Includes comprehensive input validation and error handling

#### 2. **Layout & Positioning Module** (`src/js/layout/positioning.js`)
- Extracted `positionContributorNodes()` function (~117 lines → 179
lines)
- Calculates contributor ring radius and positions nodes
- Includes configuration constants and validation
- Returns calculated values instead of mutating globals

#### 3. **Render Orchestration Module** (`src/js/render/draw.js`)
- Extracted `draw()` function (~166 lines → 198 lines)
- Orchestrates the complete rendering pipeline
- Uses dependency injection pattern for render functions
- Includes validation and error checking

### Build System Changes

#### Native ES Modules (No Bundler)
- After testing Vite bundling, switched to use native ES modules instead

#### Updated Build Process
- Modified `src/contributor_network/cli.py` to copy `src/js/` directory
to `dist/`
- Updated HTML template to properly load ES modules with `type="module"`
- Added module load event handling to ensure proper initialization order

## File Structure

```
contributor-network/
├── python/                    # Python backend
│   ├── contributor_network/   # CLI package
│   ├── tests/                 # Python tests
│   └── templates/             # Jinja2 HTML templates
├── js/                        # JavaScript frontend
│   ├── chart.js               # Main D3.js visualization (was index.js)
│   ├── index.js               # Module re-exports
│   ├── __tests__/             # JS tests
│   ├── config/                # Theme and scales
│   ├── data/                  # Data preparation
│   ├── render/                # Canvas rendering
│   └── ...
├── assets/                    # Static assets
│   ├── css/                   # Stylesheets
│   ├── data/                  # CSV data files
│   ├── img/                   # Images
│   └── lib/                   # Vendored D3 libraries
├── index.html                 # Entry point
├── pyproject.toml             # Python config (points to python/)
├── package.json               # JS config
├── config.toml, veda.toml     # Project configs
└── README.md, LICENSE, etc.
```

## Migration Notes

### For Developers

1. **Import Paths:** All imports now use relative paths from `src/js/`
2. **Module Structure:** New code should follow the established module
structure

### For Build Process

The build command remains the same:
```bash
uv run contributor-network build data dist
```

The build process now:
1. Copies CSV data files (`top_contributors.csv`, `repositories.csv`,
`links.csv`) to the destination folder
2. Copies `index.js` (main entry point) to the destination
3. Copies `src/js/` modules to `{destination}/src/js/` for native ES
module imports
4. Copies CSS, D3 library files, and images to the destination
5. Generates `index.html` from the Jinja2 template with proper ES module
script tags (`type="module"`)

---------

Co-authored-by: Pete Gadomski <pete.gadomski@gmail.com>

Author: aboydnw

.DS_Store

@@ -19,8 +19,8 @@ jobs:
           git config user.name 'github-actions[bot]'
           git config user.email 'github-actions[bot]@users.noreply.github.com'
           git checkout -b build-data
-          uv run contributor-network data data
-          uv run contributor-network csvs data
+          uv run contributor-network assets/data assets/data
+          uv run contributor-network csvs assets/data
           git add .
           git commit -m "chore: update data"
           git push -u origin build-data

.github/workflows/build.yml

@@ -20,3 +20,5 @@ jobs:
         run: uv run mypy
       - name: Test
         run: uv run pytest
+      - name: Build
+        run: uv run contributor-network build assets/data dist

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - uses: actions/configure-pages@v5
       - uses: astral-sh/setup-uv@v6
       - name: Build
-        run: uv run contributor-network build data dist
+        run: uv run contributor-network build assets/data dist
       - uses: actions/upload-pages-artifact@v3
         with:
           path: "dist"

.github/workflows/pages.yml

@@ -215,3 +215,8 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
+# Node.js
+node_modules/
+
+# macOS
+.DS_Store

.gitignore

@@ -36,19 +36,42 @@ uv run ruff check --fix .
 
 # Run tests
 uv run pytest
-uv run pytest tests/test_config.py::test_function_name  # Single test
+uv run pytest python/tests/test_config.py::test_function_name  # Single test
 ```
 
 ## Architecture
 
 **Data flow**: GitHub API → Python CLI → JSON files → CSV files → D3.js visualization
 
-- `src/contributor_network/cli.py` - Click-based CLI with 5 subcommands
-- `src/contributor_network/config.py` - Pydantic models for TOML configuration
-- `src/contributor_network/models.py` - Data models (Link, Repository)
-- `src/contributor_network/client.py` - GitHub API client wrapper
-- `index.js` - D3.js visualization (vanilla JS, no build step)
-- `templates/` - Jinja2 HTML templates
+### Folder Structure
+
+```
+python/                    # Python backend
+  contributor_network/     # CLI package
+  tests/                   # Python tests
+  templates/               # Jinja2 HTML templates
+js/                        # JavaScript frontend
+  chart.js                 # Main D3.js visualization
+  config/                  # Theme and scale configuration
+  data/                    # Data preparation and filtering
+  render/                  # Canvas rendering modules
+  simulations/             # D3 force simulations
+  ...
+assets/                    # Static assets
+  css/                     # Stylesheets
+  data/                    # CSV data files
+  img/                     # Images
+  lib/                     # Vendored D3 libraries
+```
+
+### Key Files
+
+- `python/contributor_network/cli.py` - Click-based CLI with 5 subcommands
+- `python/contributor_network/config.py` - Pydantic models for TOML configuration
+- `python/contributor_network/models.py` - Data models (Link, Repository)
+- `python/contributor_network/client.py` - GitHub API client wrapper
+- `js/chart.js` - D3.js visualization entry point
+- `python/templates/` - Jinja2 HTML templates
 - `config.toml`, `veda.toml` - Repository and contributor configuration
 
 ## Code Style

CLAUDE.md

@@ -16,11 +16,10 @@ This visual is derived from the excellent [ORCA top-contributor-network](https:/
 ### View Locally
 
 ```shell
-cd dist
 python -m http.server 8000
 ```
 
-Then open <http://localhost:8000/>.
+Then open <http://localhost:8000/> (the root index.html)
 
 ## CLI Commands
 
@@ -51,7 +50,7 @@ Fetch contribution data from GitHub for all configured repositories:
 
 ```shell
 export GITHUB_TOKEN="your_token_here"
-uv run contributor-network data data
+uv run contributor-network assets/data assets/data
 ```
 
 Options:
@@ -62,15 +61,15 @@ Options:
 Generate CSV files from the fetched JSON data:
 
 ```shell
-uv run contributor-network csvs data
+uv run contributor-network csvs assets/data
 ```
 
 ### `build`
 
 Build the static site to the `dist/` folder:
 
 ```shell
-uv run contributor-network build data dist
+uv run contributor-network build assets/data dist
 ```
 
 ## Full Workflow
@@ -87,13 +86,13 @@ uv run contributor-network discover --min-contributors 2
 # 3. Edit config.toml to add/remove repos or contributors
 
 # 4. Fetch data from GitHub
-uv run contributor-network data data
+uv run contributor-network assets/data assets/data
 
 # 5. Generate CSVs
-uv run contributor-network csvs data
+uv run contributor-network csvs assets/data
 
 # 6. Build the site
-uv run contributor-network build data dist
+uv run contributor-network build assets/data dist
 
 # 7. Preview locally
 cd dist && python -m http.server 8000
@@ -109,6 +108,46 @@ Edit `config.toml` to configure:
 
 ## Development
 
+### Architecture
+
+The visualization code is organized into modular ES6 modules in `src/js/`:
+
+```
+src/js/
+├── config/          # Configuration (theme, scales)
+├── data/            # Data filtering and utilities
+├── interaction/     # Mouse hover and click handling
+├── layout/          # Canvas sizing and layout
+├── render/          # Drawing functions (shapes, text, labels)
+├── simulations/     # D3 force simulations
+├── state/           # State management
+├── utils/           # Utilities (helpers, validation, formatters, debug)
+└── __tests__/       # Unit tests
+```
+
+The main entry point is `index.js` which:
+1. Loads dependencies (D3, etc.)
+2. Imports all modular components
+3. Exports `createContributorNetworkVisual` function
+
+The visualization is used in `dist/index.html` to render the interactive network.
+
+### Running Tests
+
+```shell
+npm test
+```
+
+Tests use Vitest and cover filtering, validation, and utility functions.
+
+### Making Changes
+
+When modifying the visualization:
+1. Edit files in `src/js/`
+2. Changes are immediately available in the browser (no build step needed)
+3. Refresh `http://localhost:8000/` to see updates
+4. Run `npm test` to verify changes don't break tests
+
 ### Code Quality
 
 ```shell

README.md

@@ -362,14 +362,63 @@ li#item-remaining::before {
 /*************** CHART ***************/
 /*************************************/
 
-/* This is all done within the createORCAVisual function */
+/* This is all done within the createContributorNetworkVisual function */
 
 #chart-container {
     position: relative;
     background-color: var(--color-background);
     width: 100%;
     min-height: 800px;
     padding: 20px;
+    box-sizing: border-box;
+    overflow: hidden;
+}
+
+#chart-zoom-controls {
+    position: absolute;
+    top: 16px;
+    right: 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    z-index: 10;
+}
+
+#chart-zoom-controls button {
+    width: 36px;
+    height: 36px;
+    border-radius: 6px;
+    border: 1px solid #ddd;
+    background: #fff;
+    color: #443F3F;
+    font-size: 20px;
+    font-weight: 700;
+    line-height: 1;
+    cursor: pointer;
+    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.12);
+    transition: transform 120ms ease, border-color 120ms ease;
+}
+
+#chart-zoom-controls svg {
+    width: 18px;
+    height: 18px;
+    display: block;
+    margin: 0 auto;
+}
+
+#zoom-reset {
+    width: 36px;
+    height: 36px;
+    padding: 0;
+}
+
+#chart-zoom-controls button:hover {
+    border-color: #CF3F02;
+    transform: translateY(-1px);
+}
+
+#chart-zoom-controls button:active {
+    transform: translateY(0);
 }
 
 #chart-zoom-controls {
@@ -379,7 +428,7 @@ li#item-remaining::before {
     display: flex;
     flex-direction: column;
     gap: 8px;
-    z-index: 2;
+    z-index: 10;
 }
 
 #chart-zoom-controls button {
@@ -421,12 +470,12 @@ li#item-remaining::before {
 
 #chart-container canvas {
     display: block;
-    margin: 0;
 }
 
 #canvas, #canvas-click {
     position: absolute;
     top: 0;
+    left: 0;
     pointer-events: none;
     z-index: 0;
     transition: opacity 200ms ease-in;