# evolutionx-10/algosketch architecture

> Architecture diagram of the GitHub repository evolutionx-10/algosketch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evolutionx-10/algosketch
- Repository: https://github.com/evolutionx-10/algosketch

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser and External
    Browser("User Browser"):::external
    Vercel("Vercel Edge Network"):::external
    GitHub("GitHub Repo"):::external

    %% Next.js App Layer
    subgraph "Next.js App (Edge/SSR/SSG)" 
        direction TB
        LayoutGlobal["Next.js App Router\n(Global Layout)"]:::code
        LayoutDashboard["Next.js App Router\n(Dashboard Layout)"]:::code
        MDXRenderer["MDX Renderer"]:::code
        UIlib["UI Library\n(Radix UI + Tailwind)"]:::ui
        Animation["Animation Engine\n(framer-motion)"]:::ui
        ThemeProvider["Theme Provider\n(next-themes)"]:::code
        ZustandStore["Zustand Store\n(State Management)"]:::code

        LayoutGlobal -->|contains| LayoutDashboard
        LayoutGlobal --> UIlib
        LayoutGlobal --> ThemeProvider
        LayoutGlobal --> MDXRenderer
        LayoutGlobal --> ZustandStore
        LayoutGlobal --> Animation
    end

    %% Dashboard Pages
    subgraph "Dashboard Pages"
        direction TB
        Overview["Algorithms Overview Page"]:::code
        SortingDash["Sorting Algorithms Page"]:::code
        SearchingDash["Searching Algorithms Page"]:::code
        StructuresDash["Data Structures Page"]:::code

        LayoutDashboard --> Overview
        Overview --> SortingDash
        Overview --> SearchingDash
        Overview --> StructuresDash
    end

    %% MDX Content
    subgraph "MDX Content"
        direction TB
        SortingMDX["Sorting MDX Pages"]:::data
        SearchingMDX["Searching MDX Pages"]:::data
    end
    SortingMDX -->|bubble, quick, merge pages| MDXRenderer
    SearchingMDX -->|binary, linear pages| MDXRenderer

    %% Visualizer Components
    subgraph "Visualizer Components"
        direction TB
        subgraph "Sorting Visualizers"
            bubble["Bubble Sort Visualizer"]:::code
            quick["Quick Sort Visualizer"]:::code
            merge["Merge Sort Visualizer"]:::code
            heap["Heap Sort Visualizer"]:::code
            insertion["Insertion Sort Visualizer"]:::code
            selection["Selection Sort Visualizer"]:::code
        end
        subgraph "Searching Visualizers"
            linear["Linear Search Visualizer"]:::code
            binary["Binary Search Visualizer"]:::code
        end
        subgraph "Data Structure Visualizers"
            stack["Stack Visualizer"]:::code
            queue["Queue Visualizer"]:::code
            linkedlist["Linked List Visualizer"]:::code
        end
        subgraph "Shared Primitives"
            shared["Bars/Nodes/Switcher"]:::ui
        end

        ZustandStore --> bubble
        ZustandStore --> quick
        ZustandStore --> merge
        ZustandStore --> heap
        ZustandStore --> insertion
        ZustandStore --> selection
        ZustandStore --> linear
        ZustandStore --> binary
        ZustandStore --> stack
        ZustandStore --> queue
        ZustandStore --> linkedlist
        bubble --> shared
        quick --> shared
        merge --> shared
        linear --> shared
        binary --> shared
        stack --> shared
        queue --> shared
        linkedlist --> shared
    end

    %% Data & Static
    MDXFiles["MDX Files"]:::data
    StaticData["Static Data"]:::data
    BrowserCache["Browser Cache"]:::data

    MDXFiles --> MDXRenderer
    StaticData --> MDXRenderer

    %% PWA Infrastructure
    subgraph "PWA Infrastructure"
        direction TB
        SW["Service Worker"]:::code
        SWReg["SW Registration"]:::code
        Manifest["Web App Manifest"]:::data
        OfflinePage["Offline Fallback Page"]:::code
        Cache["Cache Strategy"]:::data
        Browser --> SW
        SW --> Cache
        Cache --> Browser
        SWReg --> SW
        Manifest --> Browser
        OfflinePage -.-> Browser
    end

    %% Flows
    Browser -->|"HTTP/S Request"| Vercel
    Vercel -->|"Edge SSR/SSG"| LayoutGlobal
    LayoutGlobal --> Browser
    Browser -->|"Navigate"| LayoutGlobal
    Browser -->|"Activate SW"| SWReg

    %% Documentation & Assets
    Docs["Documentation & Guides"]:::data
    PublicAssets["Public Assets"]:::data
    Docs -.-> MDXFiles
    PublicAssets -.-> Browser

    %% External Hosting
    LayoutGlobal -->|"Deployed from"| GitHub
    Vercel -->|"Pulls code"| GitHub

    %% Click Events
    click LayoutGlobal "https://github.com/evolutionx-10/algosketch/blob/main/src/app/layout.tsx"
    click LayoutDashboard "https://github.com/evolutionx-10/algosketch/blob/main/src/app/dashboard/layout.tsx"
    click MDXRenderer "https://github.com/evolutionx-10/algosketch/blob/main/src/mdx-components.tsx"
    click UIlib "https://github.com/evolutionx-10/algosketch/tree/main/src/components/ui/"
    click ThemeProvider "https://github.com/evolutionx-10/algosketch/blob/main/src/components/theme-provider.tsx"
    click SW "https://github.com/evolutionx-10/algosketch/blob/main/src/app/sw.ts"
    click SWReg "https://github.com/evolutionx-10/algosketch/blob/main/src/components/service-worker-registration.tsx"
    click Manifest "https://github.com/evolutionx-10/algosketch/blob/main/src/app/manifest.ts"
    click OfflinePage "https://github.com/evolutionx-10/algosketch/blob/main/src/app/offline/page.tsx"
    click bubble "https://github.com/evolutionx-10/algosketch/blob/main/src/components/bubble/visualizer.tsx"
    click quick "https://github.com/evolutionx-10/algosketch/blob/main/src/components/quick/visualizer.tsx"
    click merge "https://github.com/evolutionx-10/algosketch/blob/main/src/components/merge/visualizer.tsx"
    click heap "https://github.com/evolutionx-10/algosketch/blob/main/src/components/heap/visualizer.tsx"
    click insertion "https://github.com/evolutionx-10/algosketch/blob/main/src/components/insertion/visualizer.tsx"
    click selection "https://github.com/evolutionx-10/algosketch/blob/main/src/components/selection/visualizer.tsx"
    click linear "https://github.com/evolutionx-10/algosketch/blob/main/src/components/linear/visualizer.tsx"
    click binary "https://github.com/evolutionx-10/algosketch/blob/main/src/components/binary/visualizer.tsx"
    click stack "https://github.com/evolutionx-10/algosketch/blob/main/src/components/stack/visualizer.tsx"
    click queue "https://github.com/evolutionx-10/algosketch/blob/main/src/components/queue/visualizer.tsx"
    click linkedlist "https://github.com/evolutionx-10/algosketch/blob/main/src/components/linkedlist/visualizer.tsx"
    click shared "https://github.com/evolutionx-10/algosketch/tree/main/src/components/shared/"
    click Docs "https://github.com/evolutionx-10/algosketch/tree/main/docs/"
    click PublicAssets "https://github.com/evolutionx-10/algosketch/tree/main/public/"

    %% Styles
    classDef code fill:#8ecae6,stroke:#219ebc,color:#023047;
    classDef data fill:#a8dadc,stroke:#457b9d,color:#1d3557,stroke-dasharray: 2 2;
    classDef ui fill:#ffb703,stroke:#fb8500,color:#370617;
    classDef external fill:#cdb4db,stroke:#9d4edd,color:#240046;
```
