Open Source · MIT Licensed · Community Driven

Help Build the Future of Algorithm Education

Eigenvue is an open-source platform for interactive algorithm visualization across classical CS, deep learning, generative AI, and quantum computing. Every contribution makes these concepts more accessible to learners worldwide.

View on GitHub Get Started

22+

Algorithms

Domains

Packages

MIT

License

Ways to Contribute

Whether you're fixing a typo or implementing a new algorithm, every contribution matters. Pick a path that matches your interests and experience.

Intermediate

Add an Algorithm

Implement a new algorithm visualization — write the generator, define metadata, and create layout mappings.

Beginner

Improve Documentation

Fix typos, clarify explanations, add examples, or write new guides. Great for a first contribution.

Varies

Fix a Bug

Browse open issues, reproduce the bug, write a failing test, then fix it. Every fix makes the platform better.

Advanced

Enhance the Renderer

Work on the Canvas 2D rendering engine — add new layout types, improve animations, or optimize performance.

Intermediate

Cross-Language Parity

Ensure Python and TypeScript generators produce byte-identical output. Write parity tests and fix divergences.

Beginner

Write Tests

Increase test coverage with unit tests (Vitest, pytest), snapshot tests, or integration tests.

Quick Start

Get the development environment running in under two minutes.

Prerequisites

Node.js

20+

npm

10+

Python

3.10+

Git

2.30+

terminal

# Clone the repository
$ git clone https://github.com/eigenvue/eigenvue.git
$ cd eigenvue
# Install web dependencies and start the dev server
$ cd web && npm install && npm run dev
  ▶ ready on http://localhost:3000
# In a separate terminal, install Python package
$ cd python && pip install -e ".[dev]"

For the full setup guide including the docs site, editor config, and troubleshooting, see the Development Setup docs.

Contribution Workflow

From fork to merged PR — here's how a typical contribution flows.

Fork & Clone

terminal

# Fork on GitHub, then clone your fork
$ git clone https://github.com/<you>/eigenvue.git
$ cd eigenvue

Create a Branch

terminal

# Create a descriptive feature branch
$ git checkout -b feature/add-linear-search

Install & Develop

terminal

# Install dependencies and start the dev server
$ cd web && npm install && npm run dev
  ▶ ready on http://localhost:3000

Test & Lint

terminal

# Run all checks before committing
$ npm run lint && npm run typecheck && npm run test
  ✓ All checks passed

Commit & Push

terminal

# Use Conventional Commits format
$ git commit -m "feat(algorithms): add linear search generator"
$ git push origin feature/add-linear-search

Open a Pull Request

terminal

# Open a PR on GitHub targeting main
$ gh pr create --title "feat: add linear search" --body "..."
  ✓ PR #42 created — CI checks running...

Project Architecture

Eigenvue is a monorepo with three main workspaces and shared infrastructure.

eigenvue/

eigenvue/
├── algorithms/          # Algorithm definitions (meta.json + generators)
│   ├── classical/       # Binary search, sorting, graph traversal
│   ├── deep-learning/   # Perceptron, backprop, convolution
│   ├── generative-ai/   # Tokenization, attention, transformers
│   └── quantum/         # Bloch sphere, quantum gates, Grover's
├── web/                 # Next.js web application
│   └── src/
│       ├── engine/      # Canvas 2D rendering engine
│       ├── components/  # React components
│       └── lib/         # Utilities, constants, SEO
├── python/              # PyPI package (pip install eigenvue)
│   └── src/eigenvue/
│       ├── generators/  # Python algorithm implementations
│       └── runner.py    # Generator runner
├── node/                # npm package (npm install eigenvue)
├── docs/                # Astro Starlight documentation
├── shared/              # Cross-language types & schemas
│   ├── types/           # Step, VisualAction, CodeHighlight
│   └── fixtures/        # Golden test fixtures
├── scripts/             # Build & validation scripts
└── tests/               # Integration & end-to-end tests

web/

Next.js 15 · React 19 · Tailwind 4 · Canvas 2D

The interactive web application with algorithm visualizations, code editor, and step-by-step playback.

python/

Python 3.10+ · Ruff · mypy · pytest

The PyPI package that mirrors TypeScript generators for use in Jupyter notebooks and scripts.

docs/

Astro · Starlight · MDX

The documentation site with contributor guides, API reference, and algorithm-specific docs.

shared/

TypeScript Types · JSON Schema · Fixtures

Cross-language type definitions, validation schemas, and golden test fixtures for parity checks.

Adding an Algorithm

The most impactful contribution — here's the process from start to finish.

Define Metadata

Create a meta.json in algorithms/<category>/<name>/ with the algorithm's name, description, category, complexity, and input schema.

algorithms/<category>/<name>/meta.json

Write the TypeScript Generator

Implement a generator function that takes input parameters and yields Step objects with visual actions, code highlights, and explanations.

algorithms/<category>/<name>/generator.ts

Write the Python Generator

Mirror the TypeScript generator in Python. Both must produce byte-identical JSON output for the same inputs.

python/src/eigenvue/generators/<name>.py

Register the Layout

If your algorithm needs a new visual layout, create a layout function in the engine and register it via registerLayout().

web/src/engine/layouts/

Write Tests & Verify Parity

Add Vitest and pytest tests. Run the parity checker to confirm cross-language output matches to ±1e-9 tolerance.

tests/ + scripts/verify-step-parity.py

Key constraint: TypeScript and Python generators must produce byte-identical JSON output for the same inputs. The CI parity checker enforces this to ±1e-9 tolerance for floating-point values.

For the complete step-by-step walkthrough, see Adding an Algorithm in the docs.

Code Standards

Consistent code keeps the project healthy. Here's what we enforce.

Conventional Commits

Every commit follows the Conventional Commits specification. Use the workspace name as the scope: web, python, docs, algorithms, or shared.

Type	Purpose
feat	A new feature (algorithm, layout, UI component)
fix	A bug fix
docs	Documentation-only changes
style	Formatting, whitespace, no logic change
refactor	Code restructuring without behavior change
test	Adding or updating tests
chore	Build system, CI, dependencies, tooling

terminal

# Examples
$ git commit -m "feat(algorithms): add linear search generator"
$ git commit -m "fix(python): correct off-by-one in merge sort"
$ git commit -m "docs: update contributing guide"

Linting & Formatting

Web

ESLint for linting, Prettier for formatting. TypeScript strict mode with no implicit any.

$ npm run lint

$ npm run format

Python

Ruff for both linting and formatting. mypy for static type checking in strict mode.

$ ruff check .

$ ruff format .

CI Checks

All checks must pass before a PR can be merged. Run them locally before pushing.

Check	Command	Scope
ESLint	npm run lint	Web
TypeScript	npm run typecheck	Web
Vitest	npm run test	Web
Next.js Build	npm run build	Web
Ruff	ruff check .	Python
mypy	mypy src/	Python
pytest	pytest	Python
Step Parity	python scripts/verify-step-parity.py	Cross-Language

terminal

# Run all CI checks locally before pushing
$ cd web && npm run lint && npm run typecheck && npm run test && cd ..
$ cd python && ruff check . && mypy src/ && pytest && cd ..
$ python scripts/verify-step-parity.py
  ✓ All 8 checks passed

Resources & Community

Everything you need to start contributing, all in one place.

Ready to Contribute?

Every algorithm visualization you add helps someone build genuine understanding. Pick an issue, fork the repo, and submit your first PR.

Find an Issue Fork the Repo

Help Build the Future of Algorithm Education

Ways to Contribute

Add an Algorithm

Improve Documentation

Fix a Bug

Enhance the Renderer

Cross-Language Parity

Write Tests

Quick Start

Prerequisites

Contribution Workflow

Fork & Clone

Create a Branch

Install & Develop

Test & Lint

Commit & Push

Open a Pull Request

Project Architecture

Adding an Algorithm

Define Metadata

Write the TypeScript Generator

Write the Python Generator

Register the Layout

Write Tests & Verify Parity

Code Standards

Conventional Commits

Linting & Formatting

CI Checks

Resources & Community

Contributor Docs

GitHub Issues

API Reference

GitHub Discussions

Ready to Contribute?