How evolutionx-10/algosketch works
Project Type and Purpose
• Project Type: Full-stack (primarily front-end) Next.js Progressive Web App
• Purpose: Interactive algorithm visualizer for sorting, searching, and data structure operations. Users step through algorithms with animated, code-driven visualizations and view explanations in multiple languages.
File Structure
• Top-Level:
– next.config.ts, middleware.ts, tsconfig.json, package.json, bun.lock → Next.js configuration, TypeScript, build/deploy setup
– docs/ → Developer-facing architecture/enhancement guides
– src/app/ → Next.js “App Router” pages and layouts (dashboard, home, offline)
– src/components/ → Reusable React components, grouped by algorithm, data structure, UI primitives, PWA hooks
– src/lib/ → Shared utilities, types, constants
– src/hooks/ → Custom React hooks (metadata, offline detection)
– src/data/ → Changelog and other static data
– mdx-components.tsx → Custom MDX wrappers
• Architectural Clues:
– App Router with nested layouts (src/app/layout.tsx, src/app/dashboard/layout.tsx)
– MDX pages for algorithm docs (page.mdx files under searching, sorting)
– Zustand or React context for state (not explicit, but README mentions Zustand)
– Service worker (src/app/sw.ts + service-worker-registration.tsx + Serwist integration) → PWA offline support
Key README Insights
• Next.js (SSR / SSG / ISR) + Turbopack
• React 19 + TypeScript + Tailwind CSS + Radix UI + Motion + MDX + Zustand + next-themes
• PWA features: offline use, installable, service worker
• Hosted on Vercel (CDN + edge caching)
• Documentation in /docs mirrors component breakdown and extension points
Main Components & Relationships
a. Frontend Layer (Next.js App)
– App Router (Server Components + Client Components)
– MDX Renderer (mdx-components.tsx)
– UI Library (Radix UI primitives + Tailwind CSS)
– Animation Engine (Motion)
– Theming (next-themes, theme-provider.tsx)
– State Management (Zustand store for algorithm state, speed, view mode)
b. Visualizer Components
– Algorithm-specific (bubble, quick, merge, linear, binary, etc.)
– Data structure visualizers (stack, queue, linked list)
– Shared components (bars, nodes, controls, legends)
c. Data & Content
– MDX content (algorithm explanations, code snippets)
– Multi-language code examples (JavaScript, Python, C, C++, Java)
– Static data (clocks, counters)
d. PWA Infrastructure
– Service Worker (sw.ts + Serwist)
– Offline page (src/app/offline/page.tsx)
– Caching strategy (assets, JSON/MDX)
– Manifest (src/app/manifest.ts)
e. Deployment & CDN
– Vercel Edge Network (SSR/SSG at edge, caching)
– Static Hosting (public/ assets)
Architectural Patterns & Design Principles
• Component-driven design: Reusable algorithm and UI building blocks
• Nested layouts: Global (layout.tsx) vs. dashboard-specific layout
• Hybrid rendering: Static generation of algorithm pages + ISR for docs
• PWA best practices: service worker registration, offline fallback
• MDX content pipeline: Treat docs and algorithm walk-through as pages
• State isolation: Each visualizer’s step state managed by hooks/store
Final Recommendations
• Be exhaustive: Break down large directories into feature areas (sorting, searching, structures)
• PWA lifecycle separately (install, cache, offline)
• Use hierarchy: Global App → Dashboard section → Algorithm pages
• Rendering modes: Server Component vs Client Component
• Performance considerations: Edge caching, SSG frequency, SW cache strategies