From b121e6e1ec9a18d4e0b7de4307d981d4519f4bb8 Mon Sep 17 00:00:00 2001 From: Solo Shun <88045720+soloshun@users.noreply.github.com> Date: Sun, 25 Jan 2026 15:00:27 +0000 Subject: [PATCH] feat: setup and add documentation application --- README.md | 3 +- apps/docs/app/_meta.js | 12 +- apps/docs/app/architecture/page.mdx | 6 - apps/docs/app/code_of_conduct/page.mdx | 134 +++ apps/docs/app/contributing/page.mdx | 1017 ++++++++++++++++ apps/docs/app/globals.css | 33 + apps/docs/app/layout.jsx | 29 +- apps/docs/app/migration/page.mdx | 6 - apps/docs/app/page.mdx | 107 +- apps/docs/app/project/_meta.js | 6 + apps/docs/app/project/architecture/page.mdx | 948 +++++++++++++++ apps/docs/app/project/migration/page.mdx | 42 + apps/docs/app/project/roadmap/page.mdx | 581 +++++++++ apps/docs/app/project/tech_stack/page.mdx | 1049 +++++++++++++++++ apps/docs/app/roadmap/page.mdx | 6 - apps/docs/app/sponsors/page.mdx | 117 ++ apps/docs/app/tech_stack/page.mdx | 6 - apps/docs/app/technical/_meta.js | 7 + apps/docs/app/technical/algorithms/_meta.js | 4 + .../technical/algorithms/bubble-sort/page.mdx | 28 + apps/docs/app/technical/algorithms/page.mdx | 8 + .../technical/algorithms/quick-sort/page.mdx | 17 + apps/docs/app/technical/big-o/page.mdx | 51 + .../app/technical/data-structures/_meta.js | 4 + .../technical/data-structures/arrays/page.mdx | 18 + .../app/technical/data-structures/page.mdx | 8 + .../technical/data-structures/trees/page.mdx | 12 + .../technical/implementation-status/page.mdx | 185 +++ apps/docs/app/technical/page.mdx | 9 + apps/docs/app/technical/visualizers/_meta.js | 4 + .../visualizers/architecture/page.mdx | 25 + apps/docs/app/technical/visualizers/page.mdx | 7 + ...RCHITECTURE.md => OPENDSA_ARCHITECTURE.md} | 0 ...ALGO_MIGRATION.md => OPENDSA_MIGRATION.md} | 0 ...OPENALGO_ROADMAP.md => OPENDSA_ROADMAP.md} | 0 ...GO_TECH_STACK.md => OPENDSA_TECH_STACK.md} | 0 apps/docs/next.config.mjs | 3 + apps/docs/package.json | 8 +- pnpm-lock.yaml | 7 +- 39 files changed, 4463 insertions(+), 44 deletions(-) delete mode 100644 apps/docs/app/architecture/page.mdx create mode 100644 apps/docs/app/code_of_conduct/page.mdx create mode 100644 apps/docs/app/contributing/page.mdx create mode 100644 apps/docs/app/globals.css delete mode 100644 apps/docs/app/migration/page.mdx create mode 100644 apps/docs/app/project/_meta.js create mode 100644 apps/docs/app/project/architecture/page.mdx create mode 100644 apps/docs/app/project/migration/page.mdx create mode 100644 apps/docs/app/project/roadmap/page.mdx create mode 100644 apps/docs/app/project/tech_stack/page.mdx delete mode 100644 apps/docs/app/roadmap/page.mdx create mode 100644 apps/docs/app/sponsors/page.mdx delete mode 100644 apps/docs/app/tech_stack/page.mdx create mode 100644 apps/docs/app/technical/_meta.js create mode 100644 apps/docs/app/technical/algorithms/_meta.js create mode 100644 apps/docs/app/technical/algorithms/bubble-sort/page.mdx create mode 100644 apps/docs/app/technical/algorithms/page.mdx create mode 100644 apps/docs/app/technical/algorithms/quick-sort/page.mdx create mode 100644 apps/docs/app/technical/big-o/page.mdx create mode 100644 apps/docs/app/technical/data-structures/_meta.js create mode 100644 apps/docs/app/technical/data-structures/arrays/page.mdx create mode 100644 apps/docs/app/technical/data-structures/page.mdx create mode 100644 apps/docs/app/technical/data-structures/trees/page.mdx create mode 100644 apps/docs/app/technical/implementation-status/page.mdx create mode 100644 apps/docs/app/technical/page.mdx create mode 100644 apps/docs/app/technical/visualizers/_meta.js create mode 100644 apps/docs/app/technical/visualizers/architecture/page.mdx create mode 100644 apps/docs/app/technical/visualizers/page.mdx rename apps/docs/internal/{OPENALGO_ARCHITECTURE.md => OPENDSA_ARCHITECTURE.md} (100%) rename apps/docs/internal/{OPENALGO_MIGRATION.md => OPENDSA_MIGRATION.md} (100%) rename apps/docs/internal/{OPENALGO_ROADMAP.md => OPENDSA_ROADMAP.md} (100%) rename apps/docs/internal/{OPENALGO_TECH_STACK.md => OPENDSA_TECH_STACK.md} (100%) diff --git a/README.md b/README.md index 2f9c983..d8ec94a 100644 --- a/README.md +++ b/README.md @@ -222,10 +222,9 @@ If you find OpenDSA useful, consider: OpenDSA is [MIT licensed](LICENSE). ----

- Made with love by the OpenDSA community + Made with love by the Solo Shun for the OpenDSA community

diff --git a/apps/docs/app/_meta.js b/apps/docs/app/_meta.js index fb3c43b..fc947e9 100644 --- a/apps/docs/app/_meta.js +++ b/apps/docs/app/_meta.js @@ -1,8 +1,8 @@ export default { - index: 'Home', - architecture: 'Architecture', - roadmap: 'Roadmap', - migration: 'Migration', - tech_stack: 'Tech Stack' + index: 'Overview', + project: 'Project Overview', + technical: 'Technical Docs', + code_of_conduct: 'Code of Conduct', + contributing: 'Contributing', + sponsors: 'Support Us☕' } - diff --git a/apps/docs/app/architecture/page.mdx b/apps/docs/app/architecture/page.mdx deleted file mode 100644 index c0c5551..0000000 --- a/apps/docs/app/architecture/page.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Architecture ---- - -This page will be migrated from `apps/docs/internal/OPENALGO_ARCHITECTURE.md`. - diff --git a/apps/docs/app/code_of_conduct/page.mdx b/apps/docs/app/code_of_conduct/page.mdx new file mode 100644 index 0000000..c9908c8 --- /dev/null +++ b/apps/docs/app/code_of_conduct/page.mdx @@ -0,0 +1,134 @@ +--- +title: Code of Conduct +description: Our pledge and standards for community participation. +--- + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +**conduct@opendsa.dev**. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/apps/docs/app/contributing/page.mdx b/apps/docs/app/contributing/page.mdx new file mode 100644 index 0000000..1985a28 --- /dev/null +++ b/apps/docs/app/contributing/page.mdx @@ -0,0 +1,1017 @@ +--- +title: Contributing +description: Guidelines and instructions for contributing to the OpenDSA project. +--- + +# Contributing to OpenDSA + +Thank you for your interest in contributing to OpenDSA! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +1. [Code of Conduct](#code-of-conduct) +2. [Getting Started](#getting-started) +3. [Development Setup](#development-setup) +4. [Project Structure](#project-structure) +5. [Making Contributions](#making-contributions) +6. [Adding a New Visualizer](#adding-a-new-visualizer) +7. [Code Style Guide](#code-style-guide) +8. [Commit Guidelines](#commit-guidelines) +9. [Pull Request Process](#pull-request-process) +10. [Issue Guidelines](#issue-guidelines) +11. [Community](#community) + + +## Code of Conduct + +By participating in this project, you agree to abide by our [Code of Conduct](/code_of_conduct). Please read it before contributing. + +**Key Points**: +- Be respectful and inclusive +- Welcome newcomers +- Accept constructive criticism +- Focus on what's best for the community + + +## Getting Started + +### Prerequisites + +Before you begin, ensure you have the following installed: + +- **Node.js**: v18.17 or higher ([Download](https://nodejs.org/)) +- **pnpm**: v8 or higher (`npm install -g pnpm`) +- **Git**: Latest version ([Download](https://git-scm.com/)) + +### Quick Start + +```bash +# 1. Fork the repository on GitHub + +# 2. Clone your fork +git clone https://github.com/soloshun/opendsa.git +cd opendsa + +# 3. Add upstream remote +git remote add upstream https://github.com/soloshun/opendsa.git + +# 4. Install dependencies +pnpm install + +# 5. Start development server +pnpm dev +``` + + +## Development Setup + +### Installing Dependencies + +```bash +# Install all dependencies for the monorepo +pnpm install +``` + +### Running Development Servers + +```bash +# Run all apps in development mode +pnpm dev + +# Run specific app +pnpm dev --filter=@opendsa/app +pnpm dev --filter=@opendsa/web +pnpm dev --filter=@opendsa/docs +``` + +### Building + +```bash +# Build all packages and apps +pnpm build + +# Build specific package +pnpm build --filter=@opendsa/algorithms +``` + +### Testing + +```bash +# Run all tests +pnpm test + +# Run tests in watch mode +pnpm test:watch + +# Run tests for specific package +pnpm test --filter=@opendsa/algorithms + +# Run E2E tests +pnpm test:e2e +``` + +### Linting and Formatting + +```bash +# Run linter +pnpm lint + +# Fix lint issues +pnpm lint:fix + +# Format code +pnpm format + +# Type check +pnpm type-check +``` + + +## Project Structure + +``` +opendsa/ +├── apps/ +│ ├── web/ # Marketing website +│ ├── app/ # Main visualizer application +│ └── docs/ # Documentation site +│ +├── packages/ +│ ├── ui/ # Shared UI components +│ ├── algorithms/ # Algorithm implementations +│ ├── visualizers/ # Visualization components +│ ├── types/ # Shared TypeScript types +│ ├── utils/ # Shared utilities +│ └── config/ # Shared configurations +│ +├── .github/ # GitHub workflows and templates +├── turbo.json # Turborepo configuration +└── package.json # Root package.json +``` + +### Package Overview + +| Package | Description | Key Files | +|---------|-------------|-----------| +| `@opendsa/app` | Main visualizer app | `app/`, `components/` | +| `@opendsa/web` | Marketing website | `app/`, `components/` | +| `@opendsa/docs` | Documentation | `pages/` | +| `@opendsa/ui` | UI components | `src/components/` | +| `@opendsa/algorithms` | Pure algorithms | `src/sorting/`, `src/searching/` | +| `@opendsa/visualizers` | Visualizer components | `src/engine/`, `src/sorting/` | +| `@opendsa/types` | TypeScript types | `src/*.types.ts` | +| `@opendsa/utils` | Utility functions | `src/` | + + +## Making Contributions + +### Types of Contributions + +We welcome many types of contributions: + +- **Bug Fixes**: Fix issues in existing code +- **New Features**: Add new functionality +- **New Visualizers**: Add algorithm visualizations +- **Documentation**: Improve or add documentation +- **Tests**: Add or improve tests +- **UI/UX**: Improve user interface and experience +- **Performance**: Optimize existing code +- **Accessibility**: Improve accessibility + +### Contribution Workflow + +```mermaid +flowchart TB + A[Find or Create Issue] --> B[Fork Repository] + B --> C[Create Feature Branch] + C --> D[Make Changes] + D --> E[Write/Update Tests] + E --> F[Commit with Conventional Commits] + F --> G[Push to Your Fork] + G --> H[Create Pull Request] + H --> I{CI Passes?} + I -->|No| D + I -->|Yes| J[Code Review] + J --> K{Changes Requested?} + K -->|Yes| D + K -->|No| L[Merge] +``` + +### Branch Naming + +Use descriptive branch names: + +``` +feature/add-quicksort-visualizer +fix/bubble-sort-animation-bug +docs/improve-contributing-guide +refactor/animation-engine +test/add-merge-sort-tests +``` + +Format: `/` + +Types: +- `feature/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `refactor/` - Code refactoring +- `test/` - Test additions/changes +- `chore/` - Maintenance tasks + + +## Adding a New Visualizer + +This is the most common contribution. Follow this guide to add a new algorithm visualizer. + +### Step 1: Create the Algorithm Implementation + +Create the pure algorithm in `packages/algorithms`: + +```typescript +// packages/algorithms/src/sorting/insertion-sort.ts + +import type { AnimationStep } from '@opendsa/types'; + +/** + * Insertion Sort Algorithm + * Time: O(n^2) average, O(n) best | Space: O(1) + */ +export function insertionSort(array: number[]): number[] { + const arr = [...array]; + + for (let i = 1; i < arr.length; i++) { + const key = arr[i]; + let j = i - 1; + + while (j >= 0 && arr[j] > key) { + arr[j + 1] = arr[j]; + j--; + } + arr[j + 1] = key; + } + + return arr; +} + +/** + * Generate animation steps for Insertion Sort + */ +export function insertionSortSteps(array: number[]): AnimationStep[] { + const steps: AnimationStep[] = []; + const arr = [...array]; + + // Initial state + steps.push({ + id: `step-0`, + type: 'highlight', + indices: [], + description: 'Starting insertion sort', + codeLineNumbers: [1], + }); + + for (let i = 1; i < arr.length; i++) { + const key = arr[i]; + let j = i - 1; + + // Highlight current element + steps.push({ + id: `step-${steps.length}`, + type: 'highlight', + indices: [i], + description: `Select element ${key} at index ${i}`, + codeLineNumbers: [4, 5], + }); + + while (j >= 0 && arr[j] > key) { + // Compare + steps.push({ + id: `step-${steps.length}`, + type: 'compare', + indices: [j, j + 1], + description: `Compare ${arr[j]} with ${key}`, + codeLineNumbers: [7], + }); + + // Shift + arr[j + 1] = arr[j]; + steps.push({ + id: `step-${steps.length}`, + type: 'swap', + indices: [j, j + 1], + values: [...arr], + description: `Shift ${arr[j]} to the right`, + codeLineNumbers: [8], + }); + + j--; + } + + // Insert + arr[j + 1] = key; + steps.push({ + id: `step-${steps.length}`, + type: 'insert', + indices: [j + 1], + values: [...arr], + description: `Insert ${key} at index ${j + 1}`, + codeLineNumbers: [10], + }); + } + + // Mark all as sorted + steps.push({ + id: `step-${steps.length}`, + type: 'mark-sorted', + indices: arr.map((_, i) => i), + description: 'Array is sorted!', + codeLineNumbers: [12], + }); + + return steps; +} +``` + +### Step 2: Add Tests + +```typescript +// packages/algorithms/src/sorting/__tests__/insertion-sort.test.ts + +import { describe, it, expect } from 'vitest'; +import { insertionSort, insertionSortSteps } from '../insertion-sort'; + +describe('insertionSort', () => { + it('sorts an array correctly', () => { + expect(insertionSort([5, 3, 8, 1, 2])).toEqual([1, 2, 3, 5, 8]); + }); + + it('handles empty array', () => { + expect(insertionSort([])).toEqual([]); + }); + + it('handles single element', () => { + expect(insertionSort([1])).toEqual([1]); + }); + + it('handles already sorted array', () => { + expect(insertionSort([1, 2, 3, 4, 5])).toEqual([1, 2, 3, 4, 5]); + }); + + it('handles reverse sorted array', () => { + expect(insertionSort([5, 4, 3, 2, 1])).toEqual([1, 2, 3, 4, 5]); + }); + + it('handles duplicates', () => { + expect(insertionSort([3, 1, 3, 2, 1])).toEqual([1, 1, 2, 3, 3]); + }); +}); + +describe('insertionSortSteps', () => { + it('generates correct number of steps', () => { + const steps = insertionSortSteps([3, 1, 2]); + expect(steps.length).toBeGreaterThan(0); + }); + + it('first step is highlight', () => { + const steps = insertionSortSteps([3, 1, 2]); + expect(steps[0].type).toBe('highlight'); + }); + + it('last step marks all as sorted', () => { + const steps = insertionSortSteps([3, 1, 2]); + expect(steps[steps.length - 1].type).toBe('mark-sorted'); + }); +}); +``` + +### Step 3: Create the Visualizer Component + +```typescript +// packages/visualizers/src/sorting/InsertionSortVisualizer.tsx + +'use client'; + +import { useRef, useEffect, useMemo } from 'react'; +import { motion, AnimatePresence } from 'framer-motion'; +import type { VisualizerProps, AnimationStep } from '@opendsa/types'; +import { cn } from '@opendsa/utils'; + +interface InsertionSortProps extends VisualizerProps {} + +export function InsertionSortVisualizer({ + data, + currentStep, + steps, + isPlaying, + speed, +}: InsertionSortProps) { + const containerRef = useRef(null); + + const currentStepData = steps[currentStep]; + const maxValue = useMemo(() => Math.max(...data, 1), [data]); + + // Get the current state of the array at this step + const displayArray = useMemo(() => { + if (currentStepData?.values) { + return currentStepData.values as number[]; + } + return data; + }, [currentStepData, data]); + + const getBarColor = (index: number): string => { + if (!currentStepData) return 'bg-primary'; + + const { type, indices } = currentStepData; + + if (type === 'mark-sorted' && indices.includes(index)) { + return 'bg-green-500'; + } + if (type === 'compare' && indices.includes(index)) { + return 'bg-yellow-500'; + } + if (type === 'swap' && indices.includes(index)) { + return 'bg-red-500'; + } + if (type === 'highlight' && indices.includes(index)) { + return 'bg-blue-500'; + } + if (type === 'insert' && indices.includes(index)) { + return 'bg-purple-500'; + } + + return 'bg-primary'; + }; + + return ( +

+ + {displayArray.map((value, index) => ( + + {displayArray.length <= 20 && ( + + {value} + + )} + + ))} + +
+ ); +} +``` + +### Step 4: Create the Controls Component + +```typescript +// packages/visualizers/src/sorting/InsertionSortControls.tsx + +'use client'; + +import { useState } from 'react'; +import { + Button, + Slider, + Input, + Card, + CardContent, +} from '@opendsa/ui'; +import { + Play, + Pause, + RotateCcw, + SkipBack, + SkipForward, + Shuffle, +} from 'lucide-react'; +import type { ControlsProps } from '@opendsa/types'; + +export function InsertionSortControls({ + onPlay, + onPause, + onReset, + onStepForward, + onStepBackward, + onSpeedChange, + onDataChange, + isPlaying, + currentStep, + totalSteps, + speed, +}: ControlsProps) { + const [arraySize, setArraySize] = useState(10); + + const generateRandomArray = () => { + const newArray = Array.from( + { length: arraySize }, + () => Math.floor(Math.random() * 100) + 1 + ); + onDataChange(newArray); + }; + + return ( + + + {/* Playback Controls */} +
+ + + + + + + +
+ + {/* Progress */} +
+ Step {currentStep + 1} of {totalSteps} +
+ + {/* Speed Control */} +
+ + onSpeedChange(value)} + min={1} + max={100} + step={1} + /> +
+ + {/* Array Controls */} +
+ setArraySize(Number(e.target.value))} + min={2} + max={50} + className="w-20" + /> + +
+ + + ); +} +``` + +### Step 5: Register the Visualizer + +```typescript +// packages/visualizers/src/sorting/insertion-sort-plugin.ts + +import type { VisualizerPlugin } from '@opendsa/types'; +import { insertionSortSteps } from '@opendsa/algorithms'; +import { InsertionSortVisualizer } from './InsertionSortVisualizer'; +import { InsertionSortControls } from './InsertionSortControls'; + +export const insertionSortPlugin: VisualizerPlugin = { + meta: { + id: 'insertion-sort', + name: 'Insertion Sort', + category: 'sorting', + description: 'A simple sorting algorithm that builds the sorted array one element at a time.', + complexity: { + time: { + best: 'O(n)', + average: 'O(n²)', + worst: 'O(n²)', + }, + space: 'O(1)', + }, + tags: ['sorting', 'comparison', 'in-place', 'stable'], + difficulty: 'beginner', + }, + component: InsertionSortVisualizer, + controls: InsertionSortControls, + generateSteps: insertionSortSteps, + defaultInput: [64, 34, 25, 12, 22, 11, 90], + defaultCode: `function insertionSort(arr) { + for (let i = 1; i < arr.length; i++) { + let key = arr[i]; + let j = i - 1; + + while (j >= 0 && arr[j] > key) { + arr[j + 1] = arr[j]; + j--; + } + arr[j + 1] = key; + } + return arr; +}`, +}; + +// Register in packages/visualizers/src/registry.ts +import { registry } from './registry'; +import { insertionSortPlugin } from './sorting/insertion-sort-plugin'; + +registry.register(insertionSortPlugin); +``` + +### Step 6: Export from Package + +```typescript +// packages/visualizers/src/index.ts + +// ... existing exports +export { InsertionSortVisualizer } from './sorting/InsertionSortVisualizer'; +export { InsertionSortControls } from './sorting/InsertionSortControls'; +export { insertionSortPlugin } from './sorting/insertion-sort-plugin'; +``` + +### Step 7: Add Documentation + +Create a documentation page explaining the algorithm: + +```mdx +// apps/docs/pages/algorithms/sorting/insertion-sort.mdx + +--- +title: Insertion Sort +description: Learn how insertion sort works with interactive visualization +--- + +# Insertion Sort + +Insertion sort is a simple sorting algorithm that builds the final sorted array +one item at a time. + +## How It Works + +1. Start from the second element (index 1) +2. Compare it with elements before it +3. Shift larger elements to the right +4. Insert the element in its correct position +5. Repeat for all elements + +## Complexity + +| Case | Time | Space | +|------|------|-------| +| Best | O(n) | O(1) | +| Average | O(n²) | O(1) | +| Worst | O(n²) | O(1) | + +## When to Use + +- Small datasets +- Nearly sorted arrays +- Online sorting (sorting as data arrives) +- When simplicity is preferred over performance + +## Interactive Demo + +Visit the [Insertion Sort Visualizer](/visualize/sorting/insertion-sort) to see +the algorithm in action. +``` + + +## Code Style Guide + +### TypeScript + +- Use strict mode +- Prefer `interface` over `type` for object shapes +- Use descriptive variable names +- Add JSDoc comments for public APIs + +```typescript +// Good +interface UserPreferences { + theme: 'light' | 'dark' | 'system'; + fontSize: number; +} + +/** + * Updates user preferences in storage + * @param preferences - The preferences to save + * @returns Promise that resolves when saved + */ +async function savePreferences(preferences: UserPreferences): Promise { + // Implementation +} + +// Avoid +type prefs = { t: string; fs: number }; +const save = async (p: any) => { /* ... */ }; +``` + +### React Components + +- Use functional components with hooks +- Prefer named exports +- Use TypeScript for props +- Extract complex logic to custom hooks + +```typescript +// Good +interface ButtonProps { + variant?: 'primary' | 'secondary'; + children: React.ReactNode; + onClick?: () => void; +} + +export function Button({ variant = 'primary', children, onClick }: ButtonProps) { + return ( + + ); +} +``` + +### File Organization + +``` +ComponentName/ +├── ComponentName.tsx # Main component +├── ComponentName.test.tsx # Tests +├── use-component-name.ts # Custom hook (if needed) +├── types.ts # Types (if complex) +└── index.ts # Exports +``` + + +## Commit Guidelines + +We use [Conventional Commits](https://www.conventionalcommits.org/) for clear, automated changelogs. + +### Format + +``` +(): + +[optional body] + +[optional footer] +``` + +### Types + +| Type | Description | +|------|-------------| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation changes | +| `style` | Code style changes (formatting) | +| `refactor` | Code refactoring | +| `perf` | Performance improvements | +| `test` | Adding or updating tests | +| `chore` | Maintenance tasks | +| `ci` | CI/CD changes | + +### Examples + +```bash +# Feature +feat(visualizers): add insertion sort visualizer + +# Bug fix +fix(animation): resolve timing issue in bubble sort + +# Documentation +docs(contributing): add visualizer creation guide + +# Multiple scopes +feat(algorithms,visualizers): add binary search +``` + +### Commit Message Guidelines + +- Use imperative mood ("add" not "added") +- First line max 72 characters +- Reference issues in footer: `Closes #123` + + +## Pull Request Process + +### Before Creating a PR + +1. **Sync with upstream** + ```bash + git fetch upstream + git rebase upstream/dev + ``` + +2. **Run all checks** + ```bash + pnpm lint + pnpm type-check + pnpm test + pnpm build + ``` + +3. **Update documentation** if needed + +### PR Template + +When you create a PR, fill out the template: + +```markdown +## Description +Brief description of changes + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation +- [ ] Refactoring + +## Related Issues +Closes #123 + +## Checklist +- [ ] My code follows the code style +- [ ] I have added tests +- [ ] All tests pass +- [ ] I have updated documentation +- [ ] I have added a changeset (if applicable) + +## Screenshots (if applicable) +``` + +### Review Process + +1. **CI Checks**: All automated checks must pass +2. **Code Review**: At least 1 maintainer approval +3. **Discussion**: Address all comments +4. **Merge**: Maintainer merges when ready + +### After Merge + +- Delete your feature branch +- Pull latest changes +- Celebrate your contribution! + + +## Issue Guidelines + +### Bug Reports + +Use the bug report template: + +```markdown +**Describe the bug** +Clear description of the bug + +**To Reproduce** +1. Go to '...' +2. Click on '....' +3. See error + +**Expected behavior** +What should happen + +**Screenshots** +If applicable + +**Environment** +- OS: [e.g. Windows 11] +- Browser: [e.g. Chrome 120] +- Version: [e.g. 1.0.0] +``` + +### Feature Requests + +Use the feature request template: + +```markdown +**Is your feature request related to a problem?** +Clear description of the problem + +**Describe the solution you'd like** +What you want to happen + +**Describe alternatives you've considered** +Other solutions you've thought about + +**Additional context** +Any other information +``` + +### Visualizer Requests + +Use the new visualizer template: + +```markdown +**Algorithm/Data Structure** +Name of the algorithm + +**Category** +- [ ] Sorting +- [ ] Searching +- [ ] Graph +- [ ] Tree +- [ ] Dynamic Programming +- [ ] Data Structure + +**Description** +Brief description of the algorithm + +**Complexity** +- Time: O(?) +- Space: O(?) + +**Resources** +Links to explanations, Wikipedia, etc. + +**Would you like to implement this?** +- [ ] Yes, I'd like to work on this +- [ ] No, just suggesting +``` + + +## Community + +### Discord + +Join our Discord server for: +- Real-time help +- Feature discussions +- Showing off your contributions +- Connecting with other contributors + +[Join Discord⛓️‍💥❌](https://discord.gg/opendsa) + +### Getting Help + +- **Discord**: Quick questions, discussions +- **GitHub Issues**: Bugs, features, documentation +- **GitHub Discussions**: General questions, ideas + +### Recognition + +We appreciate all contributions! Contributors are: +- Listed in our README +- Mentioned in release notes +- Eligible for contributor badges + + +## License + +By contributing to OpenDSA, you agree that your contributions will be licensed under the MIT License. + + +*Thank you for contributing to OpenDSA! Your efforts help make algorithm learning more accessible to everyone.* diff --git a/apps/docs/app/globals.css b/apps/docs/app/globals.css new file mode 100644 index 0000000..e89ab1d --- /dev/null +++ b/apps/docs/app/globals.css @@ -0,0 +1,33 @@ +/* apps/docs/app/globals.css */ + +/* Base text: Inter for everything */ +body { + font-family: var(--font-inter), ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif; + font-size: 0.9rem; + font-weight: 400; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +/* Code blocks: JetBrains Mono */ +code, +kbd, +samp, +pre, +code[class*="language-"], +pre[class*="language-"] { + font-family: var(--font-jetbrains-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace !important; +} + +/* Nextra code block overrides */ +.nextra-code, +.nextra-code code, +[data-rehype-pretty-code-fragment] code, +[data-rehype-pretty-code-fragment] pre { + font-family: var(--font-jetbrains-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace !important; +} + +/* Inline code */ +:not(pre)>code { + font-family: var(--font-jetbrains-mono), ui-monospace, monospace !important; +} \ No newline at end of file diff --git a/apps/docs/app/layout.jsx b/apps/docs/app/layout.jsx index dfb8774..b30f140 100644 --- a/apps/docs/app/layout.jsx +++ b/apps/docs/app/layout.jsx @@ -2,13 +2,32 @@ import { Footer, Layout, Navbar } from 'nextra-theme-docs' import { Head } from 'nextra/components' import { getPageMap } from 'nextra/page-map' import 'nextra-theme-docs/style.css' +import './globals.css' +import 'katex/dist/katex.min.css' +import { JetBrains_Mono, Inter } from "next/font/google"; +// import Image from 'next/image' + +const jetbrainsMono = JetBrains_Mono({ + variable: "--font-jetbrains-mono", + subsets: ["latin"], + display: "swap", + weight: ["100", "200", "300", "400", "500", "600", "700"], +}); + +const inter = Inter({ + variable: "--font-inter", + subsets: ["latin"], + display: "swap", + weight: ["100", "200", "300", "400", "500", "600", "700"], +}); export const metadata = { title: { default: 'OpenDSA Docs', template: '%s | OpenDSA Docs' }, - description: 'OpenDSA documentation' + description: 'OpenDSA documentation', + authors: [{ name: "Solomon Eshun" }], } const navbar = ( @@ -17,18 +36,20 @@ const navbar = ( /> ) -const footer =
{new Date().getFullYear()} © OpenDSA.
+const footer =
+ {new Date().getFullYear()} © OpenDSA by {" "} Solo Shun. +
export default async function RootLayout({ children }) { return ( - + {children} diff --git a/apps/docs/app/migration/page.mdx b/apps/docs/app/migration/page.mdx deleted file mode 100644 index 24fc5c5..0000000 --- a/apps/docs/app/migration/page.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Migration ---- - -This page will be migrated from `apps/docs/internal/OPENALGO_MIGRATION.md`. - diff --git a/apps/docs/app/page.mdx b/apps/docs/app/page.mdx index b0ec8dc..631ce11 100644 --- a/apps/docs/app/page.mdx +++ b/apps/docs/app/page.mdx @@ -1,8 +1,109 @@ --- -title: OpenDSA Docs +title: Introduction +description: Welcome to the OpenDSA documentation. --- -Welcome to the OpenDSA documentation. +# Introduction to OpenDSA -Use the sidebar to navigate. +> **See algorithms come to life** +OpenDSA is an interactive visualization platform that helps you understand how algorithms and data structures work through step-by-step animations. Whether you're: + +- **Learning** algorithms for the first time +- **Teaching** computer science concepts +- **Preparing** for technical interviews +- **Building** educational content + +OpenDSA makes complex algorithms visual and intuitive. + +## Features + +- **Interactive Visualizations** - Watch algorithms execute step-by-step with full control +- **Multiple Categories** - Sorting, searching, graphs, trees, and more +- **Code Highlighting** - See which line of code corresponds to each step +- **Speed Control** - Slow down or speed up animations +- **Shareable URLs** - Share specific visualization states with others +- **Dark/Light Mode** - Easy on the eyes, day or night +- **Keyboard Shortcuts** - Power-user friendly controls +- **Open Source** - Free forever, community-driven + +## Visualizers + +### Sorting Algorithms +- Bubble Sort +- Selection Sort +- Insertion Sort +- Quick Sort +- Merge Sort +- *More coming soon...* + +### Searching Algorithms +- Linear Search +- Binary Search +- *More coming soon...* + +### Data Structures +- Arrays +- *Linked Lists, Trees, Graphs coming soon...* + +## Quick Start + +### Try Online + +Visit [app.opendsa.dev](https://app.opendsa.dev.vercel.app) to start visualizing algorithms immediately - no installation required. + +### Run Locally + +```bash +# Clone the repository +git clone https://github.com/soloshun/opendsa.git +cd opendsa + +# Install dependencies +pnpm install + +# Start development server +pnpm dev +``` + +Open [http://localhost:3000](http://localhost:3000) in your browser. + +## Tech Stack + +| Layer | Technology | +|-------|------------| +| Framework | [Next.js 14](https://nextjs.org/) (App Router) | +| Language | [TypeScript](https://www.typescriptlang.org/) | +| Styling | [TailwindCSS](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/) | +| Animations | [Framer Motion](https://www.framer.com/motion/) + [D3.js](https://d3js.org/) | +| State | [Zustand](https://zustand-demo.pmnd.rs/) | +| Monorepo | [Turborepo](https://turbo.build/) | +| Package Manager | [pnpm](https://pnpm.io/) | +| Deployment | [Vercel](https://vercel.com/) | + +## Contributing + +We welcome contributions from everyone! Whether it's: + +- Adding new algorithm visualizers +- Fixing bugs +- Improving documentation +- Suggesting features + +See our [Contributing Guide](/contributing) to get started. + +## Community + +- **Discord**: [Join our community ⛓️‍💥❌](https://discord.gg/opendsa) +- **Twitter**: [@self.solo_shun⛓️‍💥❌](https://twitter.com/opendsa) +- **GitHub Discussions**: [Ask questions](https://github.com/soloshun/opendsa/discussions) + +
+
+

Made with ❤️ by the Solo Shun for the OpenDSA community

+ + \ No newline at end of file diff --git a/apps/docs/app/project/_meta.js b/apps/docs/app/project/_meta.js new file mode 100644 index 0000000..c0413b5 --- /dev/null +++ b/apps/docs/app/project/_meta.js @@ -0,0 +1,6 @@ +export default { + architecture: 'Architecture', + roadmap: 'Roadmap', + migration: 'Migration', + tech_stack: 'Tech Stack' +} diff --git a/apps/docs/app/project/architecture/page.mdx b/apps/docs/app/project/architecture/page.mdx new file mode 100644 index 0000000..35f4149 --- /dev/null +++ b/apps/docs/app/project/architecture/page.mdx @@ -0,0 +1,948 @@ +title: Architecture +description: Comprehensive architecture documentation for the OpenDSA algorithm visualization platform. + +# OpenDSA - System Architecture + +> Comprehensive architecture documentation for the OpenDSA algorithm visualization platform. + +## Table of Contents + +1. [Overview](#overview) +2. [High-Level Architecture](#high-level-architecture) +3. [Monorepo Structure](#monorepo-structure) +4. [Application Architecture](#application-architecture) +5. [Data Flow](#data-flow) +6. [Visualizer Plugin System](#visualizer-plugin-system) +7. [Animation Engine](#animation-engine) +8. [State Management](#state-management) +9. [Component Architecture](#component-architecture) +10. [API Design](#api-design) + + +## Overview + +OpenDSA is built as a **Turborepo monorepo** containing multiple applications and shared packages. This architecture enables: + +- **Code reuse** across applications (website, app, docs) +- **Independent deployments** for each application +- **Shared packages** for algorithms, UI components, and utilities +- **Scalable contributor experience** with clear boundaries + + +## High-Level Architecture + +```mermaid +flowchart TB; + subgraph Users [Users]; + Learner[Learner]; + Contributor[Contributor]; + Educator[Educator]; + end + + subgraph Apps [Applications]; + Web[Web - Landing Page]; + App[App - Visualizer]; + Docs[Docs - Documentation]; + end + + subgraph Packages [Shared Packages]; + UI[UI Components]; + Algorithms[Algorithms]; + Visualizers[Visualizers]; + Types[Types]; + Utils[Utils]; + Config[Config]; + end + + subgraph Infrastructure [Infrastructure]; + Vercel[Vercel Hosting]; + GitHub[GitHub Repository]; + Actions[GitHub Actions]; + end + + Users --> Apps; + Apps --> Packages; + Apps --> Infrastructure; + GitHub --> Actions; + Actions --> Vercel; +``` + +## Monorepo Structure + +```mermaid +flowchart LR; + subgraph Root[opendsa/]; + subgraph AppsDir[apps/]; + WebApp[web/]; + MainApp[app/]; + DocsApp[docs/]; + end + + subgraph PackagesDir[packages/]; + UIPackage[ui/]; + AlgoPackage[algorithms/]; + VizPackage[visualizers/]; + TypesPackage[types/]; + UtilsPackage[utils/]; + ConfigPackage[config/]; + end + + TurboConfig[turbo.json]; + RootPackage[package.json]; + Workspace[pnpm-workspace.yaml]; + end + + WebApp --> UIPackage; + WebApp --> ConfigPackage; + MainApp --> UIPackage; + MainApp --> AlgoPackage; + MainApp --> VizPackage; + MainApp --> TypesPackage; + MainApp --> UtilsPackage; + DocsApp --> UIPackage; + DocsApp --> ConfigPackage; +``` + +### Directory Details + +``` +opendsa/ +├── apps/ +│ ├── web/ # Marketing website +│ │ ├── app/ # Next.js App Router pages +│ │ │ ├── page.tsx # Landing page +│ │ │ ├── features/ # Features page +│ │ │ ├── community/ # Community page +│ │ │ ├── blog/ # Blog (MDX) +│ │ │ └── layout.tsx # Root layout +│ │ ├── components/ # Website-specific components +│ │ ├── public/ # Static assets +│ │ └── package.json +│ │ +│ ├── app/ # Main visualizer application +│ │ ├── app/ # Next.js App Router pages +│ │ │ ├── page.tsx # Dashboard +│ │ │ ├── visualize/ # Visualizer routes +│ │ │ │ └── [category]/ +│ │ │ │ └── [algorithm]/ +│ │ │ │ └── page.tsx +│ │ │ ├── playground/ # Playground mode +│ │ │ ├── learn/ # Learning paths +│ │ │ └── layout.tsx # App layout +│ │ ├── components/ # App-specific components +│ │ │ ├── visualizer/ # Visualizer wrappers +│ │ │ ├── controls/ # Control panels +│ │ │ ├── editor/ # Code editor +│ │ │ └── sidebar/ # Navigation sidebar +│ │ ├── lib/ # App utilities +│ │ │ ├── store.ts # Zustand store +│ │ │ └── hooks/ # Custom hooks +│ │ └── package.json +│ │ +│ └── docs/ # Documentation site +│ ├── app/ # Nextjs app +| │ ├── architecture/ +| | | └── page.mdx +| | └── etc... +│ ├── theme.config.tsx # Nextra config +│ ├── next.config.mjs # Next config +│ └── package.json +│ +├── packages/ +│ ├── ui/ # Shared UI components +│ │ ├── src/ +│ │ │ ├── components/ # shadcn/ui based components +│ │ │ │ ├── button.tsx +│ │ │ │ ├── card.tsx +│ │ │ │ ├── slider.tsx +│ │ │ │ └── ... +│ │ │ └── index.ts # Public exports +│ │ └── package.json +│ │ +│ ├── algorithms/ # Pure algorithm implementations +│ │ ├── src/ +│ │ │ ├── sorting/ +│ │ │ │ ├── bubble-sort.ts +│ │ │ │ ├── quick-sort.ts +│ │ │ │ ├── merge-sort.ts +│ │ │ │ ├── insertion-sort.ts +│ │ │ │ ├── selection-sort.ts +│ │ │ │ └── index.ts +│ │ │ ├── searching/ +│ │ │ │ ├── linear-search.ts +│ │ │ │ ├── binary-search.ts +│ │ │ │ ├── jump-search.ts +│ │ │ │ └── index.ts +│ │ │ ├── graph/ +│ │ │ │ ├── bfs.ts +│ │ │ │ ├── dfs.ts +│ │ │ │ ├── dijkstra.ts +│ │ │ │ └── index.ts +│ │ │ ├── tree/ +│ │ │ │ ├── bst.ts +│ │ │ │ ├── traversals.ts +│ │ │ │ └── index.ts +│ │ │ └── index.ts +│ │ ├── tests/ +│ │ └── package.json +│ │ +│ ├── visualizers/ # Visualization components +│ │ ├── src/ +│ │ │ ├── engine/ # Animation engine +│ │ │ │ ├── types.ts +│ │ │ │ ├── animation-engine.ts +│ │ │ │ ├── use-animation.ts +│ │ │ │ └── index.ts +│ │ │ ├── sorting/ +│ │ │ │ ├── BubbleSortVisualizer.tsx +│ │ │ │ ├── QuickSortVisualizer.tsx +│ │ │ │ └── index.ts +│ │ │ ├── searching/ +│ │ │ ├── graph/ +│ │ │ ├── tree/ +│ │ │ ├── registry.ts # Visualizer registry +│ │ │ └── index.ts +│ │ └── package.json +│ │ +│ ├── types/ # Shared TypeScript types +│ │ ├── src/ +│ │ │ ├── algorithm.types.ts +│ │ │ ├── visualizer.types.ts +│ │ │ ├── animation.types.ts +│ │ │ └── index.ts +│ │ └── package.json +│ │ +│ ├── utils/ # Shared utilities +│ │ ├── src/ +│ │ │ ├── array-utils.ts +│ │ │ ├── graph-utils.ts +│ │ │ ├── url-state.ts +│ │ │ └── index.ts +│ │ └── package.json +│ │ +│ └── config/ # Shared configurations +│ ├── eslint/ +│ ├── typescript/ +│ ├── tailwind/ +│ └── package.json +│ +├── .github/ +│ ├── workflows/ +│ │ ├── ci.yml +│ │ ├── release.yml +│ │ └── dependency-update.yml +│ ├── ISSUE_TEMPLATE/ +│ │ ├── bug_report.md +│ │ ├── feature_request.md +│ │ └── new_visualizer.md +│ ├── PULL_REQUEST_TEMPLATE.md +│ └── CODEOWNERS +│ +├── turbo.json +├── package.json +├── pnpm-lock.yaml +├── pnpm-workspace.yaml +├── CONTRIBUTING.md +├── CODE_OF_CONDUCT.md +├── LICENSE +└── README.md +``` + + +## Application Architecture + +### apps/app - Main Visualizer Application + +```mermaid +flowchart TB; + subgraph Pages[Pages - App Router]; + Dashboard[Dashboard Page]; + Visualize[Visualize Page]; + Playground[Playground Page]; + Learn[Learn Page]; + end + + subgraph Components[Components]; + Sidebar[Sidebar Navigation]; + VisualizerContainer[Visualizer Container]; + ControlPanel[Control Panel]; + CodeEditor[Code Editor]; + StepInfo[Step Information]; + end + + subgraph State[State Layer]; + ZustandStore[Zustand Store]; + URLState[URL State]; + LocalStorage[Local Storage]; + end + + subgraph Packages[External Packages]; + VisualizersPackage[visualizers]; + AlgorithmsPackage[algorithms]; + UIPackage2[ui]; + end + + Dashboard --> Sidebar; + Visualize --> VisualizerContainer; + Visualize --> ControlPanel; + Visualize --> CodeEditor; + Playground --> VisualizerContainer; + + VisualizerContainer --> VisualizersPackage; + ControlPanel --> UIPackage2; + CodeEditor --> Monaco[Monaco Editor]; + + Components --> State; + VisualizersPackage --> AlgorithmsPackage; +``` + +### Page Routing Structure + +```mermaid +flowchart LR; + subgraph Routes[URL Routes]; + Root["/"]; + VisualizeRoot["/visualize"]; + VisualizeCat["/visualize/sorting"]; + VisualizeAlgo["/visualize/sorting/bubble-sort"]; + PlaygroundRoute["/playground"]; + LearnRoute["/learn"]; + LearnPath["/learn/sorting-basics"]; + end + + Root --> Dashboard2[Dashboard]; + VisualizeRoot --> CategoryList[Category List]; + VisualizeCat --> AlgorithmList[Algorithm List]; + VisualizeAlgo --> VisualizerPage[Visualizer Page]; + PlaygroundRoute --> PlaygroundPage[Playground]; + LearnRoute --> LearningPaths[Learning Paths]; + LearnPath --> LessonPage[Lesson Page]; +``` + + +## Data Flow + +### Visualization Data Flow + +```mermaid +sequenceDiagram + participant User + participant UI as UI Controls + participant Store as Zustand Store + participant Engine as Animation Engine + participant Algo as Algorithm Package + participant Viz as Visualizer Component + + User->>UI: Set array [5, 3, 8, 1, 2] + UI->>Store: updateArray([5, 3, 8, 1, 2]) + User->>UI: Click "Play" + UI->>Store: play() + Store->>Algo: generateSteps(array) + Algo-->>Store: steps[] + Store->>Engine: startAnimation(steps) + + loop Each Step + Engine->>Store: setCurrentStep(n) + Store->>Viz: render(currentState) + Viz-->>User: Visual update + Engine->>Engine: wait(speed) + end + + Engine-->>Store: animationComplete() +``` + +### State Synchronization Flow + +```mermaid +flowchart LR; + subgraph Sources[State Sources]; + UserInput[User Input]; + URLParams[URL Parameters]; + Storage[Local Storage]; + end + + subgraph Store[Zustand Store]; + ArrayState[Array State]; + AnimationState[Animation State]; + PreferencesState[Preferences]; + end + + subgraph Sync[Synchronization]; + URLSync[URL Sync]; + StorageSync[Storage Sync]; + end + + UserInput --> Store; + URLParams --> URLSync; + URLSync --> Store; + Storage --> StorageSync; + StorageSync --> Store; + Store --> URLSync; + Store --> StorageSync; +``` + +## Visualizer Plugin System + +### Plugin Interface + +```typescript +// packages/types/src/visualizer.types.ts + +export type VisualizerCategory = + | 'sorting' + | 'searching' + | 'graph' + | 'tree' + | 'dp' + | 'data-structure'; + +export interface TimeComplexity { + best: string; + average: string; + worst: string; +} + +export interface Complexity { + time: TimeComplexity; + space: string; +} + +export interface VisualizerMeta { + id: string; + name: string; + category: VisualizerCategory; + description: string; + complexity: Complexity; + tags: string[]; + difficulty: 'beginner' | 'intermediate' | 'advanced'; +} + +export interface VisualizerProps { + data: T; + currentStep: number; + steps: AnimationStep[]; + isPlaying: boolean; + speed: number; +} + +export interface ControlsProps { + onPlay: () => void; + onPause: () => void; + onReset: () => void; + onStepForward: () => void; + onStepBackward: () => void; + onSpeedChange: (speed: number) => void; + onDataChange: (data: unknown) => void; + isPlaying: boolean; + currentStep: number; + totalSteps: number; + speed: number; +} + +export interface VisualizerPlugin { + meta: VisualizerMeta; + component: React.ComponentType>; + controls: React.ComponentType; + generateSteps: (input: TInput, options?: TOptions) => AnimationStep[]; + defaultInput: TInput; + defaultCode: string; + validateInput?: (input: unknown) => input is TInput; +} +``` + +### Plugin Registration + +```mermaid +flowchart TB; + subgraph Plugins[Visualizer Plugins]; + BubbleSort[BubbleSortPlugin]; + QuickSort[QuickSortPlugin]; + MergeSort[MergeSortPlugin]; + BinarySearch[BinarySearchPlugin]; + BFS[BFSPlugin]; + end + + subgraph Registry[Visualizer Registry]; + Register[register]; + Get[get]; + GetByCategory[getByCategory]; + GetAll[getAll]; + end + + subgraph App[Application]; + Router[Dynamic Router]; + Renderer[Visualizer Renderer]; + end + + Plugins --> Register; + Register --> Registry; + Router --> Get; + Get --> Renderer; +``` + +### Registry Implementation + +```typescript +// packages/visualizers/src/registry.ts + +import type { VisualizerPlugin, VisualizerCategory } from '@opendsa/types'; + +class VisualizerRegistry { + private plugins: Map = new Map(); + + register(plugin: VisualizerPlugin): void { + if (this.plugins.has(plugin.meta.id)) { + console.warn(`Plugin ${plugin.meta.id} already registered. Overwriting.`); + } + this.plugins.set(plugin.meta.id, plugin); + } + + get(id: string): VisualizerPlugin | undefined { + return this.plugins.get(id); + } + + getByCategory(category: VisualizerCategory): VisualizerPlugin[] { + return Array.from(this.plugins.values()) + .filter(plugin => plugin.meta.category === category); + } + + getAll(): VisualizerPlugin[] { + return Array.from(this.plugins.values()); + } + + getCategories(): VisualizerCategory[] { + const categories = new Set( + Array.from(this.plugins.values()).map(p => p.meta.category) + ); + return Array.from(categories); + } +} + +export const registry = new VisualizerRegistry(); +``` + + +## Animation Engine + +### Animation Types + +```typescript +// packages/types/src/animation.types.ts + +export type StepType = + | 'compare' + | 'swap' + | 'highlight' + | 'insert' + | 'delete' + | 'visit' + | 'mark-sorted' + | 'mark-found' + | 'pivot' + | 'partition'; + +export interface AnimationStep { + id: string; + type: StepType; + indices: number[]; + values?: unknown[]; + description: string; + codeLineNumbers?: number[]; + metadata?: Record; +} + +export interface AnimationState { + steps: AnimationStep[]; + currentStep: number; + isPlaying: boolean; + speed: number; // 1-100, percentage + direction: 'forward' | 'backward'; +} + +export interface AnimationControls { + play: () => void; + pause: () => void; + reset: () => void; + stepForward: () => void; + stepBackward: () => void; + goToStep: (step: number) => void; + setSpeed: (speed: number) => void; +} +``` + +### Animation Engine Architecture + +```mermaid +stateDiagram-v2 + [*] --> Idle + Idle --> Playing: play() + Playing --> Paused: pause() + Paused --> Playing: play() + Playing --> Idle: reset() + Paused --> Idle: reset() + Playing --> Completed: lastStep + Completed --> Idle: reset() + Completed --> Playing: play() from start + + Playing --> Playing: stepForward() + Paused --> Paused: stepForward() + Paused --> Paused: stepBackward() +``` + +### Animation Hook + +```typescript +// packages/visualizers/src/engine/use-animation.ts + +import { useCallback, useEffect, useRef } from 'react'; +import { useStore } from 'zustand'; +import type { AnimationStep, AnimationControls } from '@opendsa/types'; + +interface UseAnimationOptions { + steps: AnimationStep[]; + onStepChange?: (step: number, stepData: AnimationStep) => void; + onComplete?: () => void; +} + +export function useAnimation(options: UseAnimationOptions): AnimationControls { + const { steps, onStepChange, onComplete } = options; + const timerRef = useRef(null); + + // Implementation details... + + return { + play, + pause, + reset, + stepForward, + stepBackward, + goToStep, + setSpeed, + }; +} +``` + + +## State Management + +### Zustand Store Structure + +```mermaid +flowchart TB; + subgraph Store[Global Store]; + subgraph VisualizerSlice[Visualizer Slice]; + CurrentViz[currentVisualizer]; + Data[data]; + Steps[steps]; + CurrentStep[currentStep]; + end + + subgraph AnimationSlice[Animation Slice]; + IsPlaying[isPlaying]; + Speed[speed]; + Direction[direction]; + end + + subgraph PreferencesSlice[Preferences Slice]; + Theme[theme]; + EditorVisible[editorVisible]; + SidebarOpen[sidebarOpen]; + end + end + + subgraph Middleware[Middleware]; + Persist[persist]; + DevTools[devtools]; + URLSync2[url-sync]; + end + + Store --> Middleware; +``` + +### Store Implementation + +```typescript +// apps/app/lib/store.ts + +import { create } from 'zustand'; +import { persist, devtools } from 'zustand/middleware'; +import type { AnimationStep } from '@opendsa/types'; + +interface VisualizerState { + // Visualizer state + currentVisualizer: string | null; + data: unknown; + steps: AnimationStep[]; + currentStep: number; + + // Animation state + isPlaying: boolean; + speed: number; + + // Actions + setVisualizer: (id: string) => void; + setData: (data: unknown) => void; + setSteps: (steps: AnimationStep[]) => void; + setCurrentStep: (step: number) => void; + play: () => void; + pause: () => void; + reset: () => void; + setSpeed: (speed: number) => void; +} + +interface PreferencesState { + theme: 'light' | 'dark' | 'system'; + editorVisible: boolean; + sidebarOpen: boolean; + + setTheme: (theme: 'light' | 'dark' | 'system') => void; + toggleEditor: () => void; + toggleSidebar: () => void; +} + +export const useVisualizerStore = create()( + devtools( + (set, get) => ({ + currentVisualizer: null, + data: [], + steps: [], + currentStep: 0, + isPlaying: false, + speed: 50, + + setVisualizer: (id) => set({ currentVisualizer: id }), + setData: (data) => set({ data }), + setSteps: (steps) => set({ steps, currentStep: 0 }), + setCurrentStep: (step) => set({ currentStep: step }), + play: () => set({ isPlaying: true }), + pause: () => set({ isPlaying: false }), + reset: () => set({ currentStep: 0, isPlaying: false }), + setSpeed: (speed) => set({ speed }), + }), + { name: 'visualizer-store' } + ) +); + +export const usePreferencesStore = create()( + persist( + (set) => ({ + theme: 'system', + editorVisible: true, + sidebarOpen: true, + + setTheme: (theme) => set({ theme }), + toggleEditor: () => set((state) => ({ editorVisible: !state.editorVisible })), + toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })), + }), + { name: 'opendsa-preferences' } + ) +); +``` + + +## Component Architecture + +### Component Hierarchy + +```mermaid +flowchart TB; + subgraph AppLayout[App Layout]; + Header[Header]; + Sidebar2[Sidebar]; + MainContent[Main Content]; + end + + subgraph VisualizerPage[Visualizer Page]; + VisualizerHeader[Visualizer Header]; + VisualizerBody[Visualizer Body]; + VisualizerFooter[Visualizer Footer]; + end + + subgraph VisualizerBodyContent[Visualizer Body Content]; + VisualizerPanel[Visualizer Panel]; + EditorPanel[Editor Panel]; + end + + subgraph VisualizerPanelContent[Visualizer Panel]; + Canvas[Canvas/SVG]; + StepIndicator[Step Indicator]; + ControlBar[Control Bar]; + end + + subgraph EditorPanelContent[Editor Panel]; + CodeEditor2[Code Editor]; + Console[Console Output]; + end + + MainContent --> VisualizerPage; + VisualizerBody --> VisualizerBodyContent; + VisualizerBodyContent --> VisualizerPanelContent; + VisualizerBodyContent --> EditorPanelContent; +``` + +### Component Responsibilities + +| Component | Responsibility | +|-----------|---------------| +| `AppLayout` | Global layout, navigation, theme | +| `Sidebar` | Algorithm/category navigation | +| `VisualizerPage` | Page-level state, data fetching | +| `VisualizerPanel` | Render visualization, handle resize | +| `ControlBar` | Play/pause, speed, step controls | +| `EditorPanel` | Code display, syntax highlighting | +| `StepIndicator` | Current step info, progress | + + +## API Design + +### Internal Package APIs + +```typescript +// @opendsa/algorithms - Algorithm package exports +export { bubbleSort, bubbleSortSteps } from './sorting/bubble-sort'; +export { quickSort, quickSortSteps } from './sorting/quick-sort'; +export { mergeSort, mergeSortSteps } from './sorting/merge-sort'; +export { linearSearch, linearSearchSteps } from './searching/linear-search'; +export { binarySearch, binarySearchSteps } from './searching/binary-search'; +export { bfs, bfsSteps } from './graph/bfs'; +export { dfs, dfsSteps } from './graph/dfs'; + +// @opendsa/visualizers - Visualizer package exports +export { registry } from './registry'; +export { useAnimation } from './engine/use-animation'; +export { BubbleSortVisualizer } from './sorting/BubbleSortVisualizer'; +export { QuickSortVisualizer } from './sorting/QuickSortVisualizer'; +// ... other visualizers + +// @opendsa/ui - UI component exports +export { Button } from './components/button'; +export { Card } from './components/card'; +export { Slider } from './components/slider'; +export { Input } from './components/input'; +// ... other components + +// @opendsa/types - Type exports +export type { AnimationStep, StepType } from './animation.types'; +export type { VisualizerPlugin, VisualizerMeta } from './visualizer.types'; +export type { AlgorithmResult } from './algorithm.types'; +``` + +### URL State API + +```typescript +// URL structure for sharing visualizations +// https://app.opendsa.dev/visualize/sorting/bubble-sort?data=5,3,8,1,2&step=5&speed=50 + +interface URLState { + data?: string; // Comma-separated values + step?: number; // Current step + speed?: number; // Animation speed (1-100) + playing?: boolean; // Auto-play on load +} + +// Utility functions +export function encodeURLState(state: Partial): string; +export function decodeURLState(search: string): Partial; +export function useURLState(): [URLState, (state: Partial) => void]; +``` + + +## Security Considerations + +### Code Execution + +- User code runs in a **sandboxed Web Worker** +- No access to DOM, localStorage, or network +- Execution timeout limits (5 seconds default) +- Memory limits enforced + +### Input Validation + +- All user inputs validated before processing +- Array size limits (max 100 elements for visualization) +- Value range limits +- Sanitization of any user-provided strings + + +## Performance Optimizations + +### Rendering + +- **Canvas API** for large array visualizations (>50 elements) +- **SVG** for smaller, more detailed visualizations +- **React.memo** for static components +- **useMemo/useCallback** for expensive computations + +### Animation + +- **RequestAnimationFrame** for smooth animations +- **Web Workers** for step generation (large inputs) +- **Virtualization** for step history (>1000 steps) + +### Bundle Size + +- **Tree shaking** enabled for all packages +- **Dynamic imports** for visualizers (code split per visualizer) +- **Lazy loading** for Monaco Editor + + +## Accessibility + +### Requirements + +- **WCAG 2.1 AA** compliance target +- **Keyboard navigation** for all controls +- **Screen reader** announcements for step changes +- **High contrast** mode support +- **Reduced motion** preference respected + +### Implementation + +```typescript +// Accessibility hook for visualizations +export function useA11yAnnouncements() { + const announce = useCallback((message: string) => { + // Use aria-live region to announce changes + }, []); + + return { announce }; +} +``` + + +## Testing Strategy + +### Unit Tests (Vitest) + +- Algorithm correctness +- Step generation accuracy +- Utility functions +- Store actions/selectors + +### Component Tests (Testing Library) + +- Component rendering +- User interactions +- State updates +- Accessibility + +### E2E Tests (Playwright) + +- Full user flows +- Cross-browser testing +- Visual regression +- Performance benchmarks + + +## Conclusion + +This architecture provides: + +1. **Scalability** - Easy to add new algorithms and visualizers +2. **Maintainability** - Clear separation of concerns +3. **Contributor-friendly** - Well-defined plugin system +4. **Performance** - Optimized rendering and animations +5. **Accessibility** - Built-in from the start +6. **Type safety** - Full TypeScript coverage + +The modular design ensures that OpenDSA can grow with its community while maintaining code quality and user experience. diff --git a/apps/docs/app/project/migration/page.mdx b/apps/docs/app/project/migration/page.mdx new file mode 100644 index 0000000..f5634a6 --- /dev/null +++ b/apps/docs/app/project/migration/page.mdx @@ -0,0 +1,42 @@ +--- +title: Migration +description: Overview of the migration from the legacy project to OpenDSA. +--- + +# Migration to OpenDSA + +> A high-level overview of migrating from the legacy [ds-algo-deck](https://dsalgodeck.netlify.app/) project to the new OpenDSA platform. + +## Overview + +The OpenDSA project is a complete rewrite and modernization of the previous [`ds-algo-deck`](https://dsalgodeck.netlify.app/) visualization tool. This migration was driven by the need for better scalability, performance, and a more robust contributor experience. + +## Why Migrate? + +The legacy project was built with **React + Vite** and **Redux Toolkit**. While functional, as the project grew, we encountered limitations in: + +- **Scalability**: Managing a growing number of visualizers in a single repository without clear boundaries was becoming difficult. +- **Performance**: Heavy visualizations started to impact UI responsiveness. +- **Maintainability**: Mixed styling approaches (Tailwind + Styled Components) and lack of strict typing made contributions harder. + +## The New Stack + +OpenDSA introduces a modern, monorepo-based architecture: + +- **Next.js & Turborepo**: For efficient build pipelines and server-side capabilities. +- **TypeScript**: Strict type safety across the entire codebase. +- **Zustand**: Lightweight, performant state management. +- **shadcn/ui**: a cohesive, accessible design system. + +| Aspect | Legacy (ds-algo-deck) | OpenDSA | +|--------|------------------------|---------| +| **Core** | React SPA | Next.js App Router | +| **Repo** | Single Repo | Monorepo (Turborepo) | +| **State** | Redux | Zustand | +| **Styles** | Mixed | TailwindCSS + shadcn/ui | + +## Legacy Repository + +This documentation serves as the new home for the project. The old repository is kept for reference but development has moved here. + +For detailed internal migration steps used during the transition, please refer to the internal documentation or the project's commit history. diff --git a/apps/docs/app/project/roadmap/page.mdx b/apps/docs/app/project/roadmap/page.mdx new file mode 100644 index 0000000..2b5c5f3 --- /dev/null +++ b/apps/docs/app/project/roadmap/page.mdx @@ -0,0 +1,581 @@ +--- +title: Roadmap +description: A phased approach to building the ultimate algorithm visualization platform. +--- + +# OpenDSA - Product Roadmap + +> A phased approach to building the ultimate algorithm visualization platform. + +## Table of Contents + +1. [Vision](#vision) +2. [Roadmap Overview](#roadmap-overview) +3. [Phase 1: Foundation](#phase-1-foundation-mvp) +4. [Phase 2: Core Features](#phase-2-core-features) +5. [Phase 3: Community and Learning](#phase-3-community-and-learning) +6. [Phase 4: Advanced Features](#phase-4-advanced-features) +7. [Future Considerations](#future-considerations) +8. [Success Metrics](#success-metrics) + + +## Vision + +**OpenDSA** aims to be the go-to open-source platform for visualizing and learning data structures and algorithms. Our goal is to make algorithm education: + +- **Visual**: See algorithms come to life +- **Interactive**: Control and experiment with algorithms +- **Accessible**: Free and open to everyone +- **Community-driven**: Built by learners, for learners + + +## Roadmap Overview + +```mermaid +gantt + title OpenDSA Development Roadmap + dateFormat YYYY-MM + + section Phase 1 + Foundation/MVP :p1, 2026-01-24, 3M + + section Phase 2 + Core Features :p2, after p1, 3M + + section Phase 3 + Community/Learning :p3, after p2, 3M + + section Phase 4 + Advanced Features :p4, after p3, 3M +``` + +### Phase Summary + +| Phase | Focus | Duration | Status | +|-------|-------|----------|--------| +| Phase 1 | Foundation & MVP | ~3 months | Planned | +| Phase 2 | Core Features | ~3 months | Planned | +| Phase 3 | Community & Learning | ~3 months | Planned | +| Phase 4 | Advanced Features | ~3 months | Planned | + + +## Phase 1: Foundation (MVP) + +**Goal**: Establish the technical foundation and launch with essential features. + +### 1.1 Infrastructure Setup + +- [X] **Repository Setup** + - Initialize Turborepo monorepo + - Configure pnpm workspaces + - Set up TypeScript strict mode + - Configure ESLint + Prettier + - Set up Husky for git hooks + +- [ ] **CI/CD Pipeline** + - GitHub Actions for CI (lint, type-check, test, build) + - Vercel deployment configuration + - Preview deployments for PRs + - Automated dependency updates (Dependabot) + +- [ ] **Core Packages** + - `@opendsa/types` - Shared TypeScript types + - `@opendsa/config` - Shared configurations + - `@opendsa/utils` - Utility functions + +### 1.2 UI Component Library + +- [ ] **Base Components** (`@opendsa/ui`) + - Button, Input, Slider + - Card, Dialog, Popover + - Dropdown, Select, Tabs + - Toast notifications + - Theme provider (light/dark) + +- [ ] **Visualizer Components** + - Bar chart component (for sorting) + - Array visualization component + - Control panel component + - Step indicator component + - Speed slider component + +### 1.3 Animation Engine + +- [ ] **Core Engine** (`@opendsa/visualizers`) + - Step-based animation system + - Play/pause/reset controls + - Step forward/backward + - Speed control (1x - 10x) + - Animation state management + +- [ ] **Animation Hooks** + - `useAnimation` hook + - `useVisualizerStore` hook + - Keyboard shortcuts support + +### 1.4 Initial Algorithms + +- [ ] **Sorting Algorithms** (`@opendsa/algorithms`) + - Bubble Sort + - Selection Sort + - Insertion Sort + - Quick Sort + - Merge Sort + +- [ ] **Searching Algorithms** + - Linear Search + - Binary Search + +- [ ] **Data Structure Operations** + - Array: insert, delete, update, search + +### 1.5 Visualizer Application + +- [ ] **App Structure** (`apps/app`) + - Next.js App Router setup + - Layout with sidebar navigation + - Dynamic visualizer routes + - Responsive design (tablet+) + +- [ ] **Visualizer Pages** + - Sorting algorithm visualizers (5) + - Searching algorithm visualizers (2) + - Array operations visualizer + +- [ ] **Features** + - Play/pause animations + - Step-by-step mode + - Speed control + - Random array generation + - Custom array input + +### 1.6 Marketing Website + +- [X] **Landing Page** (`apps/web`) + - Hero section with demo + - Features overview + - Algorithm categories + - Call to action + +- [X] **Pages** + - Home (landing) + - Features + - About + +### 1.7 Documentation Site + +- [ ] **Initial Docs** (`apps/docs`) + - Getting started guide + - Installation instructions + - Quick start tutorial + - Contributing guide + +### 1.8 Launch Checklist + +- [ ] Domain setup (opendsa.dev) +- [ ] SEO configuration +- [ ] Analytics setup +- [ ] Error tracking (Sentry) +- [ ] README and LICENSE +- [ ] Social media presence +- [ ] Launch announcement + + +## Phase 2: Core Features + +**Goal**: Expand algorithm coverage and enhance the visualization experience. + +### 2.1 Additional Sorting Algorithms + +- [ ] Heap Sort +- [ ] Counting Sort +- [ ] Radix Sort +- [ ] Bucket Sort +- [ ] Shell Sort +- [ ] Tim Sort (simplified) + +### 2.2 Additional Searching Algorithms + +- [ ] Jump Search +- [ ] Interpolation Search +- [ ] Exponential Search +- [ ] Ternary Search + +### 2.3 Graph Algorithms + +- [ ] **Graph Data Structure** + - Graph visualization component + - Node/edge creation UI + - Adjacency list/matrix views + +- [ ] **Traversal Algorithms** + - Breadth-First Search (BFS) + - Depth-First Search (DFS) + +- [ ] **Shortest Path** + - Dijkstra's Algorithm + - Bellman-Ford Algorithm + - Floyd-Warshall Algorithm + +- [ ] **Minimum Spanning Tree** + - Prim's Algorithm + - Kruskal's Algorithm + +### 2.4 Tree Algorithms + +- [ ] **Binary Search Tree** + - Insert, Delete, Search + - Tree visualization component + - Balance visualization + +- [ ] **Tree Traversals** + - Inorder + - Preorder + - Postorder + - Level order + +- [ ] **Advanced Trees** (simplified) + - AVL Tree rotations + - Red-Black Tree concepts + +### 2.5 Data Structure Visualizers + +- [ ] **Linked List** + - Singly linked list + - Doubly linked list + - Insert, delete, reverse + +- [ ] **Stack** + - Push, pop, peek + - Expression evaluation demo + +- [ ] **Queue** + - Enqueue, dequeue + - Circular queue + - Priority queue concepts + +- [ ] **Hash Table** + - Insert, search, delete + - Collision handling visualization + +### 2.6 Enhanced Features + +- [ ] **Code Editor Integration** + - Monaco Editor setup + - Syntax highlighting + - Code step highlighting + - Multiple language support (JS, Python, Java, C++) + +- [ ] **Shareable URLs** + - Encode state in URL + - Share specific visualization state + - Deep linking to steps + +- [ ] **User Preferences** + - Theme persistence + - Speed preferences + - Layout preferences + - Keyboard shortcuts customization + +### 2.7 Performance Optimizations + +- [ ] Canvas rendering for large arrays +- [ ] Virtualization for step history +- [ ] Web Worker for step generation +- [ ] Bundle size optimization + + +## Phase 3: Community and Learning + +**Goal**: Build educational content and community engagement features. + +### 3.1 Learning Paths + +- [ ] **Structured Courses** + - "Introduction to Sorting" + - "Mastering Searching" + - "Graph Algorithms 101" + - "Trees and Recursion" + +- [ ] **Path Features** + - Progress tracking + - Prerequisites + - Estimated duration + - Difficulty levels + +### 3.2 Interactive Tutorials + +- [ ] **Guided Walkthroughs** + - Step-by-step explanations + - Interactive quizzes + - "Try it yourself" sections + - Hints and solutions + +- [ ] **Concept Explanations** + - Time complexity visualizer + - Space complexity explanations + - Big O comparison charts + - Real-world applications + +### 3.3 Challenge Mode + +- [ ] **Algorithm Challenges** + - Predict the output + - Count the steps + - Identify the algorithm + - Fix the bug + +- [ ] **Gamification** + - Points/scoring system + - Streaks and achievements + - Leaderboard (optional) + - Progress badges + +### 3.4 Community Features + +- [ ] **Discord Integration** + - Discord server setup + - Role assignments + - Channel structure + - Bot for announcements + +- [ ] **Community Submissions** + - User-submitted visualizers + - Review process + - Attribution system + +- [ ] **Feedback System** + - In-app feedback + - Feature voting + - Bug reporting + +### 3.5 Blog + +- [ ] **Algorithm Deep Dives** + - Detailed explanations + - Use case examples + - Implementation tips + +- [ ] **Community Spotlights** + - Contributor features + - Project updates + - Release notes + +### 3.6 Documentation Expansion + +- [ ] **Algorithm Reference** + - Every algorithm documented + - Complexity analysis + - Code examples + - Related problems + +- [ ] **API Documentation** + - Package APIs + - Hook documentation + - Type definitions + + +## Phase 4: Advanced Features + +**Goal**: Add power-user features and platform expansion capabilities. + +### 4.1 User Accounts (Optional) + +- [ ] **Authentication** + - GitHub OAuth + - Google OAuth + - Email/password (optional) + +- [ ] **User Features** + - Save favorite visualizations + - Track learning progress + - Custom settings sync + - Submission history + +### 4.2 Save and Load + +- [ ] **Visualization Saving** + - Save current state + - Name and organize + - Export/import JSON + +- [ ] **Collections** + - Create collections + - Share collections + - Public/private visibility + +### 4.3 Embed Widget + +- [ ] **Embeddable Component** + - iframe embed code + - Web component version + - Customization options + +- [ ] **Use Cases** + - Blog posts + - Documentation + - Educational platforms + - Coding bootcamps + +### 4.4 API + +- [ ] **Public API** + - Algorithm execution + - Step generation + - Embed configuration + +- [ ] **Integration Support** + - npm package for algorithms + - React component library + - Documentation + +### 4.5 Advanced Algorithms + +- [ ] **Dynamic Programming** + - Fibonacci visualization + - Longest Common Subsequence + - 0/1 Knapsack + - Matrix Chain Multiplication + +- [ ] **String Algorithms** + - Pattern matching (KMP) + - Rabin-Karp + - Trie operations + +- [ ] **Advanced Graph** + - Topological Sort + - Strongly Connected Components + - Network Flow concepts + +### 4.6 Mobile Experience + +- [ ] **Responsive Improvements** + - Mobile-optimized visualizations + - Touch gestures + - Portrait mode support + +- [ ] **PWA Features** + - Offline support + - Install prompt + - Push notifications (updates) + +### 4.7 Accessibility Audit + +- [ ] **WCAG 2.1 AA Compliance** + - Screen reader support + - Keyboard navigation + - High contrast mode + - Reduced motion support + +- [ ] **Documentation** + - Accessibility statement + - Known issues + - Alternative formats + +### 4.8 Internationalization + +- [ ] **i18n Setup** + - Translation framework + - Language selector + - RTL support + +- [ ] **Initial Languages** + - English (default) + - Spanish + - Chinese + - Hindi + - (Community contributions) + + +## Future Considerations + +These are ideas for future exploration, not committed features: + +### Potential Features + +- **AI-Powered Explanations**: Use LLMs to generate custom explanations +- **Collaborative Mode**: Real-time shared visualization sessions +- **VR/AR Visualization**: 3D algorithm visualization +- **Interview Prep Mode**: LeetCode-style practice integration +- **Curriculum Builder**: Tools for educators to create courses +- **Native Mobile Apps**: iOS/Android applications +- **Desktop App**: Electron-based desktop application + +### Integration Ideas + +- **LeetCode/HackerRank**: Link to practice problems +- **GitHub**: Import/export algorithm implementations +- **Notion/Obsidian**: Embed widgets +- **VS Code Extension**: In-editor visualization + + +## Success Metrics + +### Phase 1 Metrics + +| Metric | Target | +|--------|--------| +| GitHub Stars | 100+ | +| Monthly Active Users | 500+ | +| Visualizers Available | 10+ | +| Documentation Pages | 20+ | +| Contributors | 5+ | + +### Phase 2 Metrics + +| Metric | Target | +|--------|--------| +| GitHub Stars | 500+ | +| Monthly Active Users | 2,000+ | +| Visualizers Available | 30+ | +| Documentation Pages | 50+ | +| Contributors | 15+ | + +### Phase 3 Metrics + +| Metric | Target | +|--------|--------| +| GitHub Stars | 2,000+ | +| Monthly Active Users | 10,000+ | +| Learning Paths | 5+ | +| Discord Members | 500+ | +| Blog Posts | 20+ | + +### Phase 4 Metrics + +| Metric | Target | +|--------|--------| +| GitHub Stars | 5,000+ | +| Monthly Active Users | 50,000+ | +| Embed Integrations | 100+ | +| API Calls/Month | 10,000+ | +| Languages Supported | 5+ | + + +## How to Contribute to the Roadmap + +We welcome community input on our roadmap: + +1. **Feature Requests**: Open an issue with the "feature request" template +2. **Voting**: React to issues to show support for features +3. **Discussion**: Join our Discord to discuss roadmap items +4. **Implementation**: Volunteer to implement roadmap items + +### Prioritization Criteria + +Features are prioritized based on: + +1. **Impact**: How many users will benefit +2. **Effort**: Development complexity +3. **Dependencies**: What needs to be built first +4. **Community Interest**: Votes and feedback +5. **Strategic Fit**: Alignment with project vision + + +## Changelog + +| Date | Change | +|------|--------| +| 2026-01-24 | Initial roadmap created | + +*This roadmap is a living document and will be updated as the project evolves.* diff --git a/apps/docs/app/project/tech_stack/page.mdx b/apps/docs/app/project/tech_stack/page.mdx new file mode 100644 index 0000000..0fbc9ef --- /dev/null +++ b/apps/docs/app/project/tech_stack/page.mdx @@ -0,0 +1,1049 @@ +--- +title: Tech Stack +description: Comprehensive documentation of all technology choices and the rationale behind each decision. +--- + +# OpenDSA - Technology Stack + +> Comprehensive documentation of all technology choices and the rationale behind each decision. + +## Table of Contents + +1. [Overview](#overview) +2. [Core Framework](#core-framework) +3. [Build System](#build-system) +4. [UI and Styling](#ui-and-styling) +5. [Animations and Visualizations](#animations-and-visualizations) +6. [State Management](#state-management) +7. [Code Editor](#code-editor) +8. [Testing](#testing) +9. [Documentation](#documentation) +10. [Deployment](#deployment) +11. [Development Tools](#development-tools) +12. [Comparison with Current Stack](#comparison-with-current-stack) + + +## Overview + +The OpenDSA tech stack is chosen based on the following criteria: + +- **Industry Standard**: Widely adopted, well-documented technologies +- **Developer Experience**: Fast iteration, good tooling, TypeScript support +- **Performance**: Optimized for smooth animations and responsive UI +- **Open Source Friendly**: Easy for contributors to understand and work with +- **Scalability**: Can grow with the project's needs +- **Maintainability**: Long-term support, active communities + +```mermaid +flowchart TB; + subgraph Frontend[Frontend Layer]; + NextJS[Next.js 14+]; + React[React 18+]; + TypeScript[TypeScript 5+]; + end + + subgraph Build[Build Layer]; + Turborepo[Turborepo]; + PNPM[pnpm]; + end + + subgraph UI[UI Layer]; + ShadcnUI[shadcn/ui]; + TailwindCSS[TailwindCSS]; + RadixUI[Radix UI]; + end + + subgraph Animation[Animation Layer]; + FramerMotion[Framer Motion]; + D3JS[D3.js]; + CanvasAPI[Canvas API]; + end + + subgraph State[State Layer]; + Zustand[Zustand]; + TanStackQuery[TanStack Query]; + end + + subgraph Testing2[Testing Layer]; + Vitest[Vitest]; + Playwright[Playwright]; + TestingLibrary[Testing Library]; + end + + subgraph Deploy[Deployment]; + Vercel[Vercel]; + GitHubActions[GitHub Actions]; + end + + Frontend --> Build; + Frontend --> UI; + Frontend --> Animation; + Frontend --> State; + Frontend --> Testing2; + Build --> Deploy; +``` + + +## Core Framework + +### Next.js 14+ (App Router) + +**Choice**: Next.js with App Router + +**Alternatives Considered**: +- Vite + React (current stack) +- Remix +- Astro +- Create React App + +**Rationale**: + +| Feature | Next.js | Vite + React | Remix | +|---------|---------|--------------|-------| +| SSR/SSG | Built-in | Manual | Built-in | +| File-based routing | Yes | No | Yes | +| API routes | Yes | No | Yes | +| Image optimization | Built-in | Manual | Manual | +| Vercel integration | Native | Good | Good | +| App Router (RSC) | Yes | No | No | +| Community/Ecosystem | Largest | Large | Growing | + +**Key Benefits**: +1. **Server Components**: Reduce client bundle size +2. **File-based Routing**: Intuitive, less boilerplate +3. **Built-in Optimizations**: Images, fonts, scripts +4. **Vercel Deployment**: Zero-config, preview deployments +5. **SEO**: Better for marketing site +6. **Ecosystem**: Vast plugin and tool support + +**Configuration**: +```typescript +// next.config.js +/** @type {import('next').NextConfig} */ +const nextConfig = { + experimental: { + typedRoutes: true, + }, + images: { + remotePatterns: [ + { hostname: 'avatars.githubusercontent.com' }, + ], + }, + transpilePackages: [ + '@opendsa/ui', + '@opendsa/visualizers', + '@opendsa/algorithms', + ], +}; + +export default nextConfig; +``` + + +### TypeScript 5+ + +**Choice**: TypeScript with strict mode + +**Alternatives Considered**: +- JavaScript (current stack) +- JSDoc type annotations + +**Rationale**: + +1. **Type Safety**: Catch errors at compile time +2. **Better DX**: Autocomplete, refactoring support +3. **Documentation**: Types serve as documentation +4. **Contributor Experience**: Easier to understand codebase +5. **Industry Standard**: Expected for serious projects + +**Configuration**: +```json +// tsconfig.json +{ + "compilerOptions": { + "strict": true, + "noUncheckedIndexedAccess": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "exactOptionalPropertyTypes": true, + "moduleResolution": "bundler", + "module": "ESNext", + "target": "ES2022", + "lib": ["DOM", "DOM.Iterable", "ES2022"], + "jsx": "preserve", + "incremental": true, + "paths": { + "@/*": ["./src/*"], + "@opendsa/ui": ["../../packages/ui/src"], + "@opendsa/algorithms": ["../../packages/algorithms/src"], + "@opendsa/visualizers": ["../../packages/visualizers/src"], + "@opendsa/types": ["../../packages/types/src"], + "@opendsa/utils": ["../../packages/utils/src"] + } + } +} +``` + + +### pnpm + +**Choice**: pnpm as package manager + +**Alternatives Considered**: +- npm (current) +- yarn +- bun + +**Rationale**: + +| Feature | pnpm | npm | yarn | bun | +|---------|------|-----|------|-----| +| Disk space | Best | Worst | Medium | Best | +| Install speed | Fast | Slow | Medium | Fastest | +| Monorepo support | Native | Limited | Good | Growing | +| Strict mode | Yes | No | No | No | +| Stability | Excellent | Excellent | Good | Beta | + +**Key Benefits**: +1. **Efficient Storage**: Content-addressable store, symlinks +2. **Fast**: Up to 2x faster than npm +3. **Strict**: Prevents phantom dependencies +4. **Monorepo Native**: Built-in workspace support +5. **Industry Adoption**: Used by Vue, Vite, Turborepo + + +## Build System + +### Turborepo + +**Choice**: Turborepo for monorepo management + +**Alternatives Considered**: +- Nx +- Lerna +- Rush +- No monorepo (separate repos) + +**Rationale**: + +| Feature | Turborepo | Nx | Lerna | +|---------|-----------|-----|-------| +| Learning curve | Low | High | Medium | +| Build caching | Excellent | Excellent | Limited | +| Remote caching | Vercel | Nx Cloud | No | +| Configuration | Minimal | Complex | Moderate | +| Vercel integration | Native | Manual | Manual | + +**Key Benefits**: +1. **Simple Configuration**: Single `turbo.json` +2. **Intelligent Caching**: Local and remote caching +3. **Parallel Execution**: Run tasks in parallel +4. **Vercel Integration**: Free remote caching +5. **Incremental Builds**: Only rebuild what changed + +**Configuration** (Turborepo 2.0+): +```json +// turbo.json +{ + "$schema": "https://turborepo.dev/schema.json", + "globalDependencies": ["**/.env.*local"], + "tasks": { + "build": { + "dependsOn": ["^build"], + "outputs": [".next/**", "!.next/cache/**", "dist/**"] + }, + "lint": {}, + "test": { + "dependsOn": ["^build"] + }, + "dev": { + "cache": false, + "persistent": true + }, + "type-check": { + "dependsOn": ["^type-check"] + } + } +} +``` + + +## UI and Styling + +### shadcn/ui + +**Choice**: shadcn/ui component library + +**Alternatives Considered**: +- NextUI (current) +- Radix UI (raw) +- Chakra UI +- MUI (Material UI) +- Mantine + +**Rationale**: + +| Feature | shadcn/ui | NextUI | Chakra UI | MUI | +|---------|-----------|--------|-----------|-----| +| Own the code | Yes | No | No | No | +| Bundle size | Minimal | Medium | Medium | Large | +| Customization | Full | Medium | Good | Complex | +| Accessibility | Excellent | Good | Excellent | Good | +| Tailwind native | Yes | Yes | No | No | +| Learning curve | Low | Low | Medium | High | + +**Key Benefits**: +1. **Code Ownership**: Copy/paste, not a dependency +2. **Full Customization**: Modify anything +3. **Accessibility**: Built on Radix primitives +4. **Tailwind Native**: Works seamlessly +5. **Contributor Friendly**: Standard React components + +**Example Component**: +```typescript +// packages/ui/src/components/button.tsx +import * as React from "react"; +import { Slot } from "@radix-ui/react-slot"; +import { cva, type VariantProps } from "class-variance-authority"; +import { cn } from "../lib/utils"; + +const buttonVariants = cva( + "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50", + { + variants: { + variant: { + default: "bg-primary text-primary-foreground hover:bg-primary/90", + destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90", + outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground", + secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80", + ghost: "hover:bg-accent hover:text-accent-foreground", + link: "text-primary underline-offset-4 hover:underline", + }, + size: { + default: "h-10 px-4 py-2", + sm: "h-9 rounded-md px-3", + lg: "h-11 rounded-md px-8", + icon: "h-10 w-10", + }, + }, + defaultVariants: { + variant: "default", + size: "default", + }, + } +); + +export interface ButtonProps + extends React.ButtonHTMLAttributes, + VariantProps { + asChild?: boolean; +} + +const Button = React.forwardRef( + ({ className, variant, size, asChild = false, ...props }, ref) => { + const Comp = asChild ? Slot : "button"; + return ( + + ); + } +); +Button.displayName = "Button"; + +export { Button, buttonVariants }; +``` + + +### TailwindCSS 3.4+ + +**Choice**: TailwindCSS for styling + +**Alternatives Considered**: +- Styled Components (partially used in current) +- CSS Modules +- Emotion +- Vanilla CSS + +**Rationale**: + +| Feature | TailwindCSS | Styled Components | CSS Modules | +|---------|-------------|-------------------|-------------| +| Bundle size | Minimal (purged) | Runtime | Zero | +| DX | Excellent | Good | Medium | +| Design system | Built-in | Manual | Manual | +| Dark mode | Built-in | Manual | Manual | +| Responsiveness | Built-in | Manual | Manual | +| Type safety | With plugins | Partial | No | + +**Key Benefits**: +1. **Utility-First**: Fast iteration +2. **Design Tokens**: Consistent spacing, colors +3. **Dark Mode**: Built-in support +4. **Responsive**: Mobile-first utilities +5. **Purging**: Only ships used CSS +6. **Industry Standard**: Widely known + +**Configuration**: +```typescript +// tailwind.config.ts +import type { Config } from "tailwindcss"; + +const config: Config = { + darkMode: "class", + content: [ + "./app/**/*.{ts,tsx}", + "./components/**/*.{ts,tsx}", + "../../packages/ui/src/**/*.{ts,tsx}", + ], + theme: { + extend: { + colors: { + border: "hsl(var(--border))", + input: "hsl(var(--input))", + ring: "hsl(var(--ring))", + background: "hsl(var(--background))", + foreground: "hsl(var(--foreground))", + primary: { + DEFAULT: "hsl(var(--primary))", + foreground: "hsl(var(--primary-foreground))", + }, + secondary: { + DEFAULT: "hsl(var(--secondary))", + foreground: "hsl(var(--secondary-foreground))", + }, + destructive: { + DEFAULT: "hsl(var(--destructive))", + foreground: "hsl(var(--destructive-foreground))", + }, + muted: { + DEFAULT: "hsl(var(--muted))", + foreground: "hsl(var(--muted-foreground))", + }, + accent: { + DEFAULT: "hsl(var(--accent))", + foreground: "hsl(var(--accent-foreground))", + }, + // Algorithm-specific colors + compare: "hsl(var(--compare))", + swap: "hsl(var(--swap))", + sorted: "hsl(var(--sorted))", + pivot: "hsl(var(--pivot))", + visited: "hsl(var(--visited))", + current: "hsl(var(--current))", + found: "hsl(var(--found))", + }, + animation: { + "slide-in": "slideIn 0.3s ease-out", + "fade-in": "fadeIn 0.2s ease-out", + "scale-in": "scaleIn 0.2s ease-out", + "bar-swap": "barSwap 0.3s ease-in-out", + }, + keyframes: { + slideIn: { + from: { transform: "translateY(-10px)", opacity: "0" }, + to: { transform: "translateY(0)", opacity: "1" }, + }, + fadeIn: { + from: { opacity: "0" }, + to: { opacity: "1" }, + }, + scaleIn: { + from: { transform: "scale(0.95)", opacity: "0" }, + to: { transform: "scale(1)", opacity: "1" }, + }, + barSwap: { + "0%": { transform: "translateX(0)" }, + "50%": { transform: "translateY(-10px)" }, + "100%": { transform: "translateX(var(--swap-distance))" }, + }, + }, + }, + }, + plugins: [require("tailwindcss-animate")], +}; + +export default config; +``` + + +## Animations and Visualizations + +### Framer Motion + +**Choice**: Framer Motion for UI animations + +**Alternatives Considered**: +- React Spring +- GSAP +- CSS animations only +- Motion One + +**Rationale**: + +| Feature | Framer Motion | GSAP | React Spring | Motion One | +|---------|---------------|------|--------------|------------| +| React integration | Native | Wrapper | Native | Native | +| Bundle size | Medium (20kb) | Large (60kb) | Medium | Small (3kb) | +| Learning curve | Low | Medium | Medium | Low | +| Layout animations | Excellent | Manual | Limited | No | +| Gestures | Built-in | Plugin | Limited | No | +| SSR | Yes | Manual | Yes | Yes | + +**Key Benefits**: +1. **Declarative**: Animate with props +2. **Layout Animations**: `layout` prop magic +3. **Gestures**: Drag, tap, hover built-in +4. **Exit Animations**: `AnimatePresence` +5. **Spring Physics**: Natural motion + +**Use Cases in OpenDSA**: +```typescript +// Page transitions + + {children} + + +// Control panel animations + + Play + + +// Sidebar toggle + + {/* Sidebar content */} + +``` + + +### D3.js + +**Choice**: D3.js for complex data visualizations + +**Alternatives Considered**: +- Chart.js +- Recharts +- Visx +- Pure SVG/Canvas + +**Rationale**: + +| Feature | D3.js | Recharts | Visx | Chart.js | +|---------|-------|----------|------|----------| +| Flexibility | Full | Limited | Full | Limited | +| Learning curve | High | Low | Medium | Low | +| Custom visualizations | Excellent | Poor | Good | Poor | +| Animation control | Full | Limited | Good | Limited | +| SVG manipulation | Native | Abstracted | Native | Canvas | + +**Key Benefits**: +1. **Full Control**: Build any visualization +2. **Data Binding**: Efficient updates +3. **Transitions**: Smooth, customizable +4. **Scales**: Map data to visual properties +5. **Existing Knowledge**: Already used in current project + +**Use Cases in OpenDSA**: +- Graph algorithms (BFS, DFS, Dijkstra) +- Tree visualizations (BST, traversals) +- Complex sorting visualizations (bars, with animations) +- Linked list visualizations + +**Example**: +```typescript +// Graph visualization with D3 +import * as d3 from 'd3'; + +function renderGraph(container: HTMLElement, nodes: Node[], edges: Edge[]) { + const svg = d3.select(container) + .append('svg') + .attr('width', '100%') + .attr('height', '100%'); + + const simulation = d3.forceSimulation(nodes) + .force('link', d3.forceLink(edges).id(d => d.id)) + .force('charge', d3.forceManyBody().strength(-300)) + .force('center', d3.forceCenter(width / 2, height / 2)); + + // Render edges + const link = svg.selectAll('.link') + .data(edges) + .join('line') + .attr('class', 'link') + .attr('stroke', '#999'); + + // Render nodes + const node = svg.selectAll('.node') + .data(nodes) + .join('circle') + .attr('class', 'node') + .attr('r', 20) + .attr('fill', d => d.visited ? 'var(--visited)' : 'var(--default)'); + + // Update positions on tick + simulation.on('tick', () => { + link + .attr('x1', d => d.source.x) + .attr('y1', d => d.source.y) + .attr('x2', d => d.target.x) + .attr('y2', d => d.target.y); + + node + .attr('cx', d => d.x) + .attr('cy', d => d.y); + }); +} +``` + + +### Canvas API + +**Choice**: Canvas API for high-performance array visualizations + +**Rationale**: +- **Performance**: Handle 100+ elements at 60fps +- **Control**: Pixel-level manipulation +- **Memory**: Lower memory usage than SVG for many elements + +**Use Cases**: +- Large array sorting visualizations (>50 elements) +- Performance-critical animations +- Real-time data updates + +**Example**: +```typescript +// High-performance array visualization +function renderArray( + canvas: HTMLCanvasElement, + array: number[], + highlights: Map +) { + const ctx = canvas.getContext('2d')!; + const { width, height } = canvas; + const barWidth = width / array.length; + const maxValue = Math.max(...array); + + ctx.clearRect(0, 0, width, height); + + array.forEach((value, index) => { + const barHeight = (value / maxValue) * (height - 20); + const x = index * barWidth; + const y = height - barHeight; + + // Set color based on state + ctx.fillStyle = highlights.get(index) || 'hsl(var(--primary))'; + ctx.fillRect(x + 1, y, barWidth - 2, barHeight); + + // Draw value label for small arrays + if (array.length <= 30) { + ctx.fillStyle = 'hsl(var(--foreground))'; + ctx.font = '12px sans-serif'; + ctx.textAlign = 'center'; + ctx.fillText(value.toString(), x + barWidth / 2, y - 5); + } + }); +} +``` + + +## State Management + +### Zustand + +**Choice**: Zustand for global state + +**Alternatives Considered**: +- Redux Toolkit (current) +- Jotai +- Recoil +- React Context + +**Rationale**: + +| Feature | Zustand | Redux Toolkit | Jotai | Context | +|---------|---------|---------------|-------|---------| +| Bundle size | 1kb | 11kb | 2kb | 0kb | +| Boilerplate | Minimal | Medium | Minimal | Medium | +| Learning curve | Low | Medium | Low | Low | +| DevTools | Yes | Excellent | Yes | Limited | +| TypeScript | Excellent | Good | Excellent | Good | +| Middleware | Yes | Yes | Limited | Manual | + +**Key Benefits**: +1. **Simplicity**: Minimal boilerplate +2. **Performance**: Selective re-renders out of box +3. **TypeScript**: Great type inference +4. **Flexibility**: No providers required +5. **Size**: Tiny bundle impact + +**Store Structure**: +```typescript +// Visualization store +interface VisualizerStore { + // State + visualizerId: string | null; + data: unknown; + steps: AnimationStep[]; + currentStep: number; + isPlaying: boolean; + speed: number; + + // Actions + setVisualizer: (id: string) => void; + setData: (data: unknown) => void; + generateSteps: () => void; + play: () => void; + pause: () => void; + reset: () => void; + stepForward: () => void; + stepBackward: () => void; + setSpeed: (speed: number) => void; +} + +// Preferences store (persisted) +interface PreferencesStore { + theme: 'light' | 'dark' | 'system'; + editorVisible: boolean; + sidebarOpen: boolean; + keyboardShortcutsEnabled: boolean; + + setTheme: (theme: 'light' | 'dark' | 'system') => void; + toggleEditor: () => void; + toggleSidebar: () => void; + toggleKeyboardShortcuts: () => void; +} +``` + + +## Code Editor + +### Monaco Editor + +**Choice**: Monaco Editor (same as VS Code) + +**Alternatives Considered**: +- CodeMirror 6 +- Ace Editor +- Prism.js (display only) + +**Rationale**: + +| Feature | Monaco | CodeMirror 6 | Ace | +|---------|--------|--------------|-----| +| IntelliSense | Full | Plugin | Limited | +| Bundle size | Large (2MB) | Medium | Medium | +| Features | Complete | Good | Good | +| Familiarity | VS Code | Learning | Old | +| TypeScript | Native | Plugin | Plugin | + +**Key Benefits**: +1. **VS Code Experience**: Familiar to developers +2. **IntelliSense**: Autocomplete, errors +3. **TypeScript**: Native support +4. **Themes**: VS Code themes work + +**Configuration**: +```typescript +// Monaco editor setup +import { Editor, OnMount } from '@monaco-editor/react'; + +interface CodeEditorProps { + code: string; + language: string; + highlightLines?: number[]; + readOnly?: boolean; + onChange?: (value: string) => void; +} + +export function CodeEditor({ + code, + language, + highlightLines = [], + readOnly = false, + onChange, +}: CodeEditorProps) { + const handleMount: OnMount = (editor, monaco) => { + // Configure editor + editor.updateOptions({ + minimap: { enabled: false }, + lineNumbers: 'on', + scrollBeyondLastLine: false, + readOnly, + fontSize: 14, + }); + + // Highlight lines + if (highlightLines.length > 0) { + editor.deltaDecorations([], highlightLines.map(line => ({ + range: new monaco.Range(line, 1, line, 1), + options: { + isWholeLine: true, + className: 'highlighted-line', + glyphMarginClassName: 'highlighted-glyph', + }, + }))); + } + }; + + return ( + onChange?.(value ?? '')} + theme="vs-dark" + /> + ); +} +``` + + +## Testing + +### Vitest + +**Choice**: Vitest for unit testing + +**Alternatives Considered**: +- Jest +- Node test runner +- Mocha + +**Rationale**: + +| Feature | Vitest | Jest | +|---------|--------|------| +| Speed | Fast (native ESM) | Slower | +| Vite integration | Native | Manual | +| Watch mode | Excellent | Good | +| API compatibility | Jest-compatible | - | +| TypeScript | Native | Plugin | + +**Configuration**: +```typescript +// vitest.config.ts +import { defineConfig } from 'vitest/config'; +import react from '@vitejs/plugin-react'; + +export default defineConfig({ + plugins: [react()], + test: { + environment: 'jsdom', + globals: true, + setupFiles: ['./test/setup.ts'], + coverage: { + provider: 'v8', + reporter: ['text', 'json', 'html'], + exclude: ['node_modules/', 'test/'], + }, + }, +}); +``` + + +### Playwright + +**Choice**: Playwright for E2E testing + +**Alternatives Considered**: +- Cypress +- Puppeteer +- TestCafe + +**Rationale**: + +| Feature | Playwright | Cypress | +|---------|------------|---------| +| Browsers | All | Chrome, Firefox, Edge | +| Speed | Faster | Slower | +| Auto-wait | Better | Good | +| Parallelism | Built-in | Paid | +| Cross-origin | Yes | Limited | + +**Configuration**: +```typescript +// playwright.config.ts +import { defineConfig, devices } from '@playwright/test'; + +export default defineConfig({ + testDir: './e2e', + fullyParallel: true, + forbidOnly: !!process.env.CI, + retries: process.env.CI ? 2 : 0, + workers: process.env.CI ? 1 : undefined, + reporter: 'html', + use: { + baseURL: 'http://localhost:3000', + trace: 'on-first-retry', + }, + projects: [ + { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, + { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, + { name: 'webkit', use: { ...devices['Desktop Safari'] } }, + ], + webServer: { + command: 'pnpm dev', + url: 'http://localhost:3000', + reuseExistingServer: !process.env.CI, + }, +}); +``` + + +## Documentation + +### Nextra + +**Choice**: Nextra for documentation site + +**Alternatives Considered**: +- Docusaurus +- Fumadocs +- VitePress +- GitBook + +**Rationale**: + +| Feature | Nextra | Docusaurus | Fumadocs | +|---------|--------|------------|----------| +| Framework | Next.js | React | Next.js | +| Setup | Simple | Medium | Simple | +| MDX | Native | Native | Native | +| Search | Built-in | Plugin | Built-in | +| Customization | Full | Good | Full | + +**Key Benefits**: +1. **Next.js Native**: Same stack as apps +2. **MDX**: React components in docs +3. **Search**: Full-text search built-in +4. **Theme**: Beautiful default theme +5. **Simple**: Minimal configuration + + +## Deployment + +### Vercel + +**Choice**: Vercel for hosting + +**Alternatives Considered**: +- Netlify (current) +- AWS Amplify +- Cloudflare Pages +- Self-hosted + +**Rationale**: + +| Feature | Vercel | Netlify | Cloudflare | +|---------|--------|---------|------------| +| Next.js support | Native | Good | Good | +| Preview deployments | Yes | Yes | Yes | +| Edge functions | Native | Beta | Native | +| Turborepo caching | Native | No | No | +| Pricing | Free tier | Free tier | Free tier | + +**Key Benefits**: +1. **Next.js Creator**: Best Next.js support +2. **Preview Deployments**: Per-PR previews +3. **Turborepo Integration**: Remote caching +4. **Zero Config**: Automatic detection +5. **Free for OSS**: Open source program + + +### GitHub Actions + +**Workflows**: + +1. **CI (ci.yml)**: Runs on every PR + - Lint + - Type check + - Unit tests + - Build verification + +2. **Release (release.yml)**: On merge to main + - Deploy to production + - Create release notes + - Update changelog + +3. **Dependency Update**: Weekly + - Dependabot PRs + - Security scanning + + +## Development Tools + +### ESLint + Prettier + +**Configuration**: +```javascript +// eslint.config.js +import eslint from '@eslint/js'; +import tseslint from 'typescript-eslint'; +import react from 'eslint-plugin-react'; +import reactHooks from 'eslint-plugin-react-hooks'; + +export default tseslint.config( + eslint.configs.recommended, + ...tseslint.configs.strictTypeChecked, + { + plugins: { + react, + 'react-hooks': reactHooks, + }, + rules: { + 'react-hooks/rules-of-hooks': 'error', + 'react-hooks/exhaustive-deps': 'warn', + '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }], + }, + } +); +``` + + +## Comparison with Current Stack + +| Aspect | Current (ds-algo-deck) | New (OpenDSA) | Reason for Change | +|--------|------------------------|----------------|-------------------| +| **Framework** | React + Vite | Next.js 14 | SSR, SEO, file routing, Vercel integration | +| **Language** | JavaScript | TypeScript | Type safety, better DX, documentation | +| **Package Manager** | npm | pnpm | Speed, disk efficiency, strict mode | +| **Build** | Single app | Turborepo | Code sharing, independent deployments | +| **UI Library** | NextUI | shadcn/ui | Code ownership, customization, smaller bundle | +| **State** | Redux Toolkit | Zustand | Simplicity, smaller bundle, less boilerplate | +| **Styling** | Tailwind + Styled Components | Tailwind only | Consistency, simpler mental model | +| **Animations** | Framer Motion + D3 | Same + Canvas | Add Canvas for performance | +| **Testing** | None | Vitest + Playwright | Quality assurance, contributor confidence | +| **Docs** | Markdown files | Nextra | Professional documentation site | +| **Deploy** | Netlify | Vercel | Better Next.js support, Turborepo integration | +| **CI/CD** | Manual | GitHub Actions | Automation, quality gates | + + +## Summary + +The OpenDSA tech stack is carefully chosen to provide: + +1. **Modern Foundation**: Next.js + TypeScript + pnpm +2. **Scalable Architecture**: Turborepo monorepo +3. **Beautiful UI**: shadcn/ui + TailwindCSS +4. **Smooth Animations**: Framer Motion + D3.js + Canvas +5. **Simple State**: Zustand +6. **Quality Assurance**: Vitest + Playwright +7. **Great DX**: ESLint + Prettier + TypeScript +8. **Easy Deployment**: Vercel + GitHub Actions + +This stack balances **developer experience**, **performance**, **maintainability**, and **contributor friendliness** - all essential for a successful open-source project. diff --git a/apps/docs/app/roadmap/page.mdx b/apps/docs/app/roadmap/page.mdx deleted file mode 100644 index 395d1c6..0000000 --- a/apps/docs/app/roadmap/page.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Roadmap ---- - -This page will be migrated from `apps/docs/internal/OPENALGO_ROADMAP.md`. - diff --git a/apps/docs/app/sponsors/page.mdx b/apps/docs/app/sponsors/page.mdx new file mode 100644 index 0000000..417b464 --- /dev/null +++ b/apps/docs/app/sponsors/page.mdx @@ -0,0 +1,117 @@ +# Support OpenDSA + +OpenDSA is 100% free and open source. We believe everyone should have access to quality algorithm visualizations for learning. No paywalls. No premium tiers. Just pure, open education. + +## Why Support Us? + +We're committed to keeping OpenDSA free forever. Your support helps us: + +- **Host reliable infrastructure** - Fast servers, CDN, and uptime +- **Develop new features** - More algorithms, better visualizations +- **Maintain the project** - Bug fixes, security updates, documentation +- **Grow the community** - Events, educational content, outreach + +## Current Hosting + +OpenDSA is currently hosted on **Vercel's free tier**. As the project grows, we may need to scale to handle more traffic and features. + + +## How to Support + +### GitHub Sponsors (Coming Soon) +Support the maintainers directly through GitHub Sponsors. Every contribution helps keep the project alive. + +**Setup:** [github.com/sponsors](https://github.com/sponsors) - Account pending + +### Open Collective (Coming Soon) +For transparent, community-managed funding. All expenses and contributions are public. + +**Setup:** [opencollective.com](https://opencollective.com) - Account pending + +### Buy Me a Coffee (Coming Soon) +Quick one-time donations to fuel late-night coding sessions. + +**Setup:** [buymeacoffee.com](https://www.buymeacoffee.com) - Account pending + +### Ko-fi (Coming Soon) +Another great platform for one-time or monthly support. + +**Setup:** [ko-fi.com](https://ko-fi.com) - Account pending + +### Patreon (Coming Soon) +For those who want to support with monthly contributions. + +**Setup:** [patreon.com](https://www.patreon.com) - Account pending + + +## Corporate Sponsors + +Are you a company that values open source education? We'd love to partner with you! + +### Sponsorship Tiers + +#### Bronze - $50/month +- Logo on README +- Shoutout on social media + +#### Silver - $100/month +- Everything in Bronze +- Logo on website footer +- Monthly progress updates + +#### Gold - $250/month +- Everything in Silver +- Logo on homepage +- Featured in release notes + +#### Platinum - $500+/month +- Everything in Gold +- Custom feature prioritization +- Direct support channel + +**Interested?** Reach out at [GitHub Discussions](https://github.com/soloshun/opendsa/discussions) or email us at [solomoneshun373@gmail.com](mailto:solomoneshun373@gmail.com). + + +## Current Sponsors + +*Be the first to support OpenDSA!* + +No sponsors yet. Your logo could be here. + + +## Other Ways to Help + +Don't have the funds? No problem! You can still contribute: + +1. **Star the repo** - Helps with visibility +2. **Share on social media** - Spread the word +3. **Write a blog post** - Review or tutorial +4. **Report bugs** - Help us improve +5. **Submit PRs** - Code contributions welcome +6. **Answer questions** - Help others in discussions + + +## Transparency + +We believe in open finances. Once we set up Open Collective or similar platforms, all income and expenses will be publicly visible. + +**Current Monthly Costs:** \$0 (Vercel free tier)
+**Expected at Scale:** ~\$50-200/month (Pro hosting, domain, services) + + +## FAQ + +### Will OpenDSA ever have paid features? +No. OpenDSA will always be 100% free. Sponsorships help us maintain and improve the free platform. + +### Where does the money go? +Hosting costs, domain registration, and development tools. Any surplus goes toward bounties for contributors. + +### Can I sponsor anonymously? +Yes, most platforms support anonymous donations. + +### Is my donation tax-deductible? +Depends on your country and the platform used. Open Collective offers fiscal hosting which may provide tax benefits in some jurisdictions. + + +*Thank you for considering supporting OpenDSA. Every contribution, big or small, helps keep algorithm education free and accessible to everyone.* diff --git a/apps/docs/app/tech_stack/page.mdx b/apps/docs/app/tech_stack/page.mdx deleted file mode 100644 index a0c9fb5..0000000 --- a/apps/docs/app/tech_stack/page.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Tech Stack ---- - -This page will be migrated from `apps/docs/internal/OPENALGO_TECH_STACK.md`. - diff --git a/apps/docs/app/technical/_meta.js b/apps/docs/app/technical/_meta.js new file mode 100644 index 0000000..47a289f --- /dev/null +++ b/apps/docs/app/technical/_meta.js @@ -0,0 +1,7 @@ +export default { + "implementation-status": 'Implementation Status', + "big-o": 'Big O Notation', + "data-structures": 'Data Structures', + algorithms: 'Algorithms', + visualizers: 'Visualizers' +} diff --git a/apps/docs/app/technical/algorithms/_meta.js b/apps/docs/app/technical/algorithms/_meta.js new file mode 100644 index 0000000..5eff340 --- /dev/null +++ b/apps/docs/app/technical/algorithms/_meta.js @@ -0,0 +1,4 @@ +export default { + "bubble-sort": "Bubble Sort", + "quick-sort": "Quick Sort" +} diff --git a/apps/docs/app/technical/algorithms/bubble-sort/page.mdx b/apps/docs/app/technical/algorithms/bubble-sort/page.mdx new file mode 100644 index 0000000..0743a73 --- /dev/null +++ b/apps/docs/app/technical/algorithms/bubble-sort/page.mdx @@ -0,0 +1,28 @@ +# Bubble Sort + +Bubble Sort is the simplest sorting algorithm that works by repeatedly swapping the adjacent elements if they are in the wrong order. + +## Complexity + +| Type | Complexity | +| :--- | :--- | +| **Time (Worst)** | $O(n^2)$ | +| **Time (Average)** | $O(n^2)$ | +| **Time (Best)** | $O(n)$ | +| **Space** | $O(1)$ | + +## Implementation + +```typescript +function bubbleSort(arr: number[]): number[] { + const n = arr.length; + for (let i = 0; i < n; i++) { + for (let j = 0; j < n - i - 1; j++) { + if (arr[j] > arr[j + 1]) { + [arr[j], arr[j + 1]] = [arr[j + 1], arr[j]]; + } + } + } + return arr; +} +``` diff --git a/apps/docs/app/technical/algorithms/page.mdx b/apps/docs/app/technical/algorithms/page.mdx new file mode 100644 index 0000000..3f3af89 --- /dev/null +++ b/apps/docs/app/technical/algorithms/page.mdx @@ -0,0 +1,8 @@ +# Algorithms + +The current version of OpenDSA implements value-based algorithms to help users understand core computer science concepts. + +## Sorting Implementations + +- [Bubble Sort](/technical/algorithms/bubble-sort) +- [Quick Sort](/technical/algorithms/quick-sort) diff --git a/apps/docs/app/technical/algorithms/quick-sort/page.mdx b/apps/docs/app/technical/algorithms/quick-sort/page.mdx new file mode 100644 index 0000000..e79c253 --- /dev/null +++ b/apps/docs/app/technical/algorithms/quick-sort/page.mdx @@ -0,0 +1,17 @@ +# Quick Sort + +Quick Sort is an efficient, divide-and-conquer sorting algorithm. It works by selecting a 'pivot' element and partitioning the other elements into two sub-arrays according to whether they are less than or greater than the pivot. + +## Complexity + +| Type | Complexity | +| :--- | :--- | +| **Time (Worst)** | $O(n^2)$ | +| **Time (Average)** | $O(n \log n)$ | +| **Time (Best)** | $O(n \log n)$ | +| **Space** | $O(\log n)$ | + +## Concepts + +- **Pivot Selection**: Choosing the right pivot is crucial for performance. +- **Partitioning**: Reordering the array so that elements < pivot come before elements > pivot. diff --git a/apps/docs/app/technical/big-o/page.mdx b/apps/docs/app/technical/big-o/page.mdx new file mode 100644 index 0000000..4c689f2 --- /dev/null +++ b/apps/docs/app/technical/big-o/page.mdx @@ -0,0 +1,51 @@ +# Big O Notation + +Big O notation is a mathematical notation that describes the limiting behavior of a function when the argument tends towards a particular value or infinity. In computer science, it is used to classify algorithms according to how their run time or space requirements grow as the input size grows. + +## Common Time Complexities + +| Notation | Name | Description | Example | +| :--- | :--- | :--- | :--- | +| **O(1)** | Constant | Execution time is independent of input size. | Accessing array index | +| **O(log n)** | Logarithmic | Time grows logarithmically with input size. | Binary Search | +| **O(n)** | Linear | Time grows linearly with input size. | Linear Search | +| **O(n log n)** | Linearithmic | Faster than quadratic but slower than linear. | Merge Sort, Quick Sort | +| **O(n²)** | Quadratic | Time grows with the square of the input size. | Bubble Sort | +| **O(2ⁿ)** | Exponential | Time doubles with each addition to input. | Recursive Fibonacci | +| **O(n!)** | Factorial | Growth is factorial based on input size. | Traveling Salesperson | + +## Why it Matters + +Understanding Big O helps developers: +- Predict performance at scale. +- Choose the right algorithm for the job. +- Identify bottlenecks in code. + +### Visualizing Growth + +```mermaid +graph LR + A["Input Size (n)"] --> B{Complexity} + B -->|O 1| C[Instant] + B -->|O log n| D[Fast] + B -->|O n| E[Manageable] + B -->|O n^2| F[Slow] + B -->|O 2^n| G["Unusable for large n"] +``` + +### Complexity Chart + +```mermaid +xychart-beta + title "Time Complexity Growth" + x-axis "Input Size (n)" [1, 2, 4, 8, 16] + y-axis "Operations" 0 --> 300 + line [1, 1, 1, 1, 1] + line [1, 2, 4, 8, 16] + line [1, 4, 16, 64, 256] +``` +
+
O(1)
+
O(n)
+
O(n²)
+
diff --git a/apps/docs/app/technical/data-structures/_meta.js b/apps/docs/app/technical/data-structures/_meta.js new file mode 100644 index 0000000..5bbe0bc --- /dev/null +++ b/apps/docs/app/technical/data-structures/_meta.js @@ -0,0 +1,4 @@ +export default { + arrays: "Arrays", + trees: "Trees" +} diff --git a/apps/docs/app/technical/data-structures/arrays/page.mdx b/apps/docs/app/technical/data-structures/arrays/page.mdx new file mode 100644 index 0000000..c6c9cb0 --- /dev/null +++ b/apps/docs/app/technical/data-structures/arrays/page.mdx @@ -0,0 +1,18 @@ +# Arrays + +An array is a collection of items stored at contiguous memory locations. It is one of the simplest and most widely used data structures. + +## Complexity + +| Operation | Complexity | +| :--- | :--- | +| **Access** | $O(1)$ | +| **Search** | $O(n)$ | +| **Insertion** | $O(n)$ | +| **Deletion** | $O(n)$ | + +## Visualization + +In OpenDSA, arrays are visualized as a row of bars or boxes. +- **Highlight**: Change color to indicate comparison or access. +- **Swap**: Animate position exchange. diff --git a/apps/docs/app/technical/data-structures/page.mdx b/apps/docs/app/technical/data-structures/page.mdx new file mode 100644 index 0000000..1f92f3a --- /dev/null +++ b/apps/docs/app/technical/data-structures/page.mdx @@ -0,0 +1,8 @@ +# Data Structures + +Core data structures implemented in OpenDSA with interactive visualizations. + +## Available Data Structures + +- [Arrays](/technical/data-structures/arrays) - Linear collection of elements +- [Trees](/technical/data-structures/trees) - Hierarchical node-based structures diff --git a/apps/docs/app/technical/data-structures/trees/page.mdx b/apps/docs/app/technical/data-structures/trees/page.mdx new file mode 100644 index 0000000..7a1dc2a --- /dev/null +++ b/apps/docs/app/technical/data-structures/trees/page.mdx @@ -0,0 +1,12 @@ +# Trees + +Trees are hierarchical data structures consisting of nodes connected by edges. + +## Binary Search Tree (BST) + +A binary tree where the key in each node is greater than all keys in the left subtree and less than all keys in the right subtree. + +### Properties +- **Root**: Topmost node. +- **Leaf**: Node with no children. +- **Height**: Number of edges on the longest path from node to leaf. diff --git a/apps/docs/app/technical/implementation-status/page.mdx b/apps/docs/app/technical/implementation-status/page.mdx new file mode 100644 index 0000000..53b87c0 --- /dev/null +++ b/apps/docs/app/technical/implementation-status/page.mdx @@ -0,0 +1,185 @@ +# Implementation Status + +This page tracks the implementation progress of all algorithms and data structures in OpenDSA. Want to contribute? Pick any item marked with ○ and start building! + +## Progress Overview + +**Total Items:** 70+ +**Implemented:** 4 +**In Progress:** Community-driven development + +--- + +## Data Structures + +### Arrays +| Topic | Status | +|-------|--------| +| Basic Array Operations | ✅ Implemented | +| Dynamic Arrays | ○ Pending | +| Multi-dimensional Arrays | ○ Pending | + +### Linked Lists +| Topic | Status | +|-------|--------| +| Singly Linked List | ○ Pending | +| Doubly Linked List | ○ Pending | +| Circular Linked List | ○ Pending | + +### Stacks +| Topic | Status | +|-------|--------| +| Basic Stack Operations | ○ Pending | +| Applications (Balancing Parentheses) | ○ Pending | + +### Queues +| Topic | Status | +|-------|--------| +| Basic Queue | ○ Pending | +| Circular Queue | ○ Pending | +| Priority Queue | ○ Pending | +| Deque (Double-Ended Queue) | ○ Pending | + +### Trees +| Topic | Status | +|-------|--------| +| Binary Tree | ○ Pending | +| Binary Search Tree (BST) | ○ Pending | +| AVL Tree (Self-Balancing BST) | ○ Pending | +| Red-Black Tree | ○ Pending | +| Segment Tree | ○ Pending | +| Trie | ○ Pending | +| B-Tree and B+ Tree | ○ Pending | + +### Heaps +| Topic | Status | +|-------|--------| +| Min Heap | ○ Pending | +| Max Heap | ○ Pending | +| Fibonacci Heap | ○ Pending | + +### Graphs +| Topic | Status | +|-------|--------| +| Directed/Undirected Graphs | ○ Pending | +| Weighted/Unweighted Graphs | ○ Pending | +| Adjacency Matrix | ○ Pending | +| Adjacency List | ○ Pending | +| Edge List | ○ Pending | + +### Hashing +| Topic | Status | +|-------|--------| +| Hash Tables | ○ Pending | +| Hash Maps | ○ Pending | +| Open Addressing | ○ Pending | +| Separate Chaining | ○ Pending | + +--- + +## Algorithms + +### Sorting (Easy) +| Topic | Status | +|-------|--------| +| Bubble Sort | ✅ Implemented | +| Selection Sort | ○ Pending | +| Insertion Sort | ○ Pending | + +### Sorting (Intermediate) +| Topic | Status | +|-------|--------| +| Merge Sort | ○ Pending | +| Quick Sort | ○ Pending | + +### Sorting (Advanced) +| Topic | Status | +|-------|--------| +| Heap Sort | ○ Pending | +| Counting Sort | ○ Pending | +| Radix Sort | ○ Pending | +| Bucket Sort | ○ Pending | + +### Searching +| Topic | Status | +|-------|--------| +| Linear Search | ✅ Implemented | +| Binary Search | ○ Pending | +| Jump Search | ○ Pending | +| Exponential Search | ○ Pending | + +### Graph Algorithms +| Topic | Status | +|-------|--------| +| Breadth-First Search (BFS) | ○ Pending | +| Depth-First Search (DFS) | ○ Pending | +| Dijkstra's Algorithm | ○ Pending | +| Floyd-Warshall | ○ Pending | +| Bellman-Ford | ○ Pending | +| Prim's MST | ○ Pending | +| Kruskal's MST | ○ Pending | +| A* Search | ○ Pending | + +### Dynamic Programming +| Topic | Status | +|-------|--------| +| Fibonacci | ○ Pending | +| Coin Change (Minimum Coins) | ○ Pending | +| Longest Common Subsequence (LCS) | ○ Pending | +| Knapsack Problem | ○ Pending | +| Matrix Chain Multiplication | ○ Pending | + +### Backtracking +| Topic | Status | +|-------|--------| +| Rat in a Maze | ○ Pending | +| N-Queens Problem | ○ Pending | +| Knight's Tour | ○ Pending | +| Sudoku Solver | ○ Pending | + +### Greedy Algorithms +| Topic | Status | +|-------|--------| +| Activity Selection | ○ Pending | +| Fractional Knapsack | ○ Pending | +| Huffman Coding | ○ Pending | +| Job Sequencing | ○ Pending | + +### Miscellaneous Algorithms +| Topic | Status | +|-------|--------| +| Sieve of Eratosthenes (Prime Numbers) | ○ Pending | +| Euclidean Algorithm (GCD) | ○ Pending | +| KMP Pattern Matching | ○ Pending | +| Rabin-Karp Algorithm | ○ Pending | +| Bit Manipulation | ○ Pending | +| Randomized Algorithms (QuickSelect) | ○ Pending | + +--- + +## Future Plans + +### Machine Learning Visualizers (Coming Soon) +- Linear Regression +- Logistic Regression +- Decision Trees +- K-Means Clustering +- Neural Network Forward/Backward Pass +- Gradient Descent + +### Deep Learning Visualizers (Coming Soon) +- Convolutional Neural Networks (CNN) +- Recurrent Neural Networks (RNN) +- Transformer Architecture +- Attention Mechanisms + +--- + +## How to Contribute + +1. **Pick an item** - Choose any pending (○) algorithm or data structure +2. **Create an issue** - Let the community know you're working on it +3. **Build the visualizer** - Follow our [architecture guide](/project/architecture) +4. **Submit a PR** - Reference the issue in your pull request + +See our [Contributing Guide](/contributing) for detailed instructions. diff --git a/apps/docs/app/technical/page.mdx b/apps/docs/app/technical/page.mdx new file mode 100644 index 0000000..2c43071 --- /dev/null +++ b/apps/docs/app/technical/page.mdx @@ -0,0 +1,9 @@ +# Technical Documentation + +Detailed documentation of the internal implementation of OpenDSA. + +## Sections + +- [Data Structures](/technical/data-structures): Implementation details of core data structures. +- [Algorithms](/technical/algorithms): Documentation of sorting, searching, graph, and tree algorithms. +- [Visualizers](/technical/visualizers): Architecture of the visualization engine and plugin system. diff --git a/apps/docs/app/technical/visualizers/_meta.js b/apps/docs/app/technical/visualizers/_meta.js new file mode 100644 index 0000000..c814c72 --- /dev/null +++ b/apps/docs/app/technical/visualizers/_meta.js @@ -0,0 +1,4 @@ +export default { + architecture: "Architecture" +} + diff --git a/apps/docs/app/technical/visualizers/architecture/page.mdx b/apps/docs/app/technical/visualizers/architecture/page.mdx new file mode 100644 index 0000000..ef9d349 --- /dev/null +++ b/apps/docs/app/technical/visualizers/architecture/page.mdx @@ -0,0 +1,25 @@ +# Visualizer Architecture + +The core of OpenDSA is the extensible visualizer system. + +## Key Concepts + +### Plugin System +Each algorithm visualization is a "Plugin" that provides: +- **Meta**: Name, category, complexity. +- **Component**: The React component rendering the visualization. +- **Generator**: A function that generates animation steps. + +### Example: Bubble Sort +```typescript +export const BubbleSortPlugin: VisualizerPlugin = { + meta: { + id: "bubble-sort", + name: "Bubble Sort", + category: "sorting", + complexity: { time: { worst: "O(n²)", ... }, space: "O(1)" } + }, + component: BubbleSortRenderer, + generateSteps: generateBubbleSortSteps +}; +``` diff --git a/apps/docs/app/technical/visualizers/page.mdx b/apps/docs/app/technical/visualizers/page.mdx new file mode 100644 index 0000000..4528e55 --- /dev/null +++ b/apps/docs/app/technical/visualizers/page.mdx @@ -0,0 +1,7 @@ +# Visualizers + +The OpenDSA visualizer system powers all algorithm and data structure animations. + +## Documentation + +- [Architecture](/technical/visualizers/architecture) - Core visualizer architecture and plugin system diff --git a/apps/docs/internal/OPENALGO_ARCHITECTURE.md b/apps/docs/internal/OPENDSA_ARCHITECTURE.md similarity index 100% rename from apps/docs/internal/OPENALGO_ARCHITECTURE.md rename to apps/docs/internal/OPENDSA_ARCHITECTURE.md diff --git a/apps/docs/internal/OPENALGO_MIGRATION.md b/apps/docs/internal/OPENDSA_MIGRATION.md similarity index 100% rename from apps/docs/internal/OPENALGO_MIGRATION.md rename to apps/docs/internal/OPENDSA_MIGRATION.md diff --git a/apps/docs/internal/OPENALGO_ROADMAP.md b/apps/docs/internal/OPENDSA_ROADMAP.md similarity index 100% rename from apps/docs/internal/OPENALGO_ROADMAP.md rename to apps/docs/internal/OPENDSA_ROADMAP.md diff --git a/apps/docs/internal/OPENALGO_TECH_STACK.md b/apps/docs/internal/OPENDSA_TECH_STACK.md similarity index 100% rename from apps/docs/internal/OPENALGO_TECH_STACK.md rename to apps/docs/internal/OPENDSA_TECH_STACK.md diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index 54eff3a..17f832f 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -2,6 +2,9 @@ import nextra from 'nextra' const withNextra = nextra({ // Nextra-specific options can go here. + latex: true, + // This helps with code block parsing + defaultShowCopyCode: true, }) export default withNextra({ diff --git a/apps/docs/package.json b/apps/docs/package.json index 8a4bdba..7526f03 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -8,10 +8,12 @@ "start": "next start" }, "dependencies": { + "@theguild/remark-mermaid": "^0.3.0", + "katex": "^0.16.27", "next": "16.1.4", - "react": "19.2.3", - "react-dom": "19.2.3", "nextra": "^4.6.1", - "nextra-theme-docs": "^4.6.1" + "nextra-theme-docs": "^4.6.1", + "react": "19.2.3", + "react-dom": "19.2.3" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 99b5866..ace5cd6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -53,7 +53,7 @@ importers: version: 9.39.2(jiti@2.6.1) eslint-config-next: specifier: 16.1.4 - version: 16.1.4(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3) + version: 16.1.4(@typescript-eslint/parser@8.53.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3) tailwindcss: specifier: ^4 version: 4.1.18 @@ -66,6 +66,9 @@ importers: '@theguild/remark-mermaid': specifier: ^0.3.0 version: 0.3.0(react@19.2.3) + katex: + specifier: ^0.16.27 + version: 0.16.27 next: specifier: 16.1.4 version: 16.1.4(@babel/core@7.28.6)(react-dom@19.2.3(react@19.2.3))(react@19.2.3) @@ -132,7 +135,7 @@ importers: version: 9.39.2(jiti@2.6.1) eslint-config-next: specifier: 16.1.4 - version: 16.1.4(@typescript-eslint/parser@8.53.1(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3) + version: 16.1.4(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3) tailwindcss: specifier: ^4 version: 4.1.18