chore: Modularize frontend architecture and remove ORCA code

[aboydnw]

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.

¹ 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:

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")

[aboydnw]

@gadomski I think this is ready for a review. It's a big PR...as I was adding more features and making styling tweaks, it felt pretty brittle. So I thought it would be worth cleaning out a lot of the unused code so I can more easily experiment with new features next.

[gadomski]

Awesome, thanks for taking this on. Totally agree that the monolith was heinous to deal with, this should improve. Couple of changes needed before I check functionality:

• Looks like some files got blown up to the top level that shouldn't have been
• Can we organize code like this, at the top level
  • python/
  • js/
  • package.json and pyproject.toml can both stay at the top level, and should just point to the correct source code locations

[gadomski]

Code organization change requests

[gadomski]

In general, it'd be better to keep the refactor and the functional changes (e.g. to client.py) separate, but since it's been done no need to rewind.

[aboydnw]

@gadomski okay I think this is ready for review now 😅 a good learning experience for me, sorry for the back and forth!

[gadomski]

@aboydnw it looks like the data directory moved down into assets/data, so I updated CI and README accordingly. If it's wrong we'll fix later. Thanks for the iterations and the refactor!!!