# nicodos/magic-cursor architecture

> Architecture diagram of the GitHub repository nicodos/magic-cursor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nicodos/magic-cursor
- Repository: https://github.com/nicodos/magic-cursor

## Overview

##### Main components
- Library Core Components – These are implemented under the lib directory. They include:
- Cursor Component (lib/components/Cursor.tsx) which likely renders the custom cursor.
- Element Component (lib/components/Element.tsx) which wraps target elements and adjusts cursor behavior.
- Context and Providers – Managed by:
- CursorContext (lib/contexts/CursorContext.ts) that propagates cursor state.
- CursorProvider (lib/providers/CursorProvider.tsx) which initializes and provides the context to the application.
- Custom Hooks – Found in lib/hooks (e.g., useFollowPointer, useWindowScroll) which manage dynamic behaviors such as pointer tracking and scroll influence.
- Constants, Styles, and Types – These support the functionality (e.g., configuration constants, CSS styles in lib/styles/cursor.css, and TypeScript definitions).

##### Relationships and interactions
- At the top level, the MagicCursorProvider (exported from lib/index.ts) wraps the application and provides the context to the MagicCursor component.
- The MagicCursor component uses hooks (like useFollowPointer) to track mouse movement and renders the cursor accordingly.
- The custom hooks and context ensure that any changes (such as hover state or viewport scrolling) are effectively communicated and the cursor’s appearance is dynamically updated.

##### Important architectural patterns and design principles
- Component-based architecture common in React applications.
- Use of Context API (via CursorContext/Provider) for global state management.
- Separation of concerns: the core “cursor” logic (rendering and tracking) is separated from interaction controlled via the “elements”.
- Modular design making it easy to maintain and extend (components, hooks, contexts are in separate directories).

##### Relevant technologies and frameworks
- React (for component rendering and context management).
- TypeScript (as indicated by .ts and .tsx files and tsconfig.json) ensuring type safety.
- Vite (evident from the vite.config.mjs file) for development/build tooling.
- ESLint, Prettier for code formatting and linting.
- Jest for testing (jest.config.js, jest.setup.ts and test files).

##### Instructing creation
- Use clear labels for each component. For example: “MagicCursorProvider (Context Provider)”, “MagicCursor (Display Component)”, “MagicElement (Interactive Wrapper)”, “useFollowPointer (Custom Hook)”, etc.
- Adding an external “User Application” layer to show how the library integrates in a full React app.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Integration
    UA["User Application"]:::ui

    %% Library Entry Point
    ENTRY["Library Entry Point"]:::config

    %% Subgraph: Library Core Components
    subgraph "Library Core Components"
        MC["MagicCursor (Display Component)"]:::ui
        ME["MagicElement (Interactive Wrapper)"]:::ui
    end

    %% Subgraph: Context and Provider
    subgraph "Context & Provider"
        MCP["MagicCursorProvider (Context Provider)"]:::provider
        CC["CursorContext (Context Component)"]:::provider
    end

    %% Subgraph: Custom Hooks
    subgraph "Custom Hooks"
        HF["useFollowPointer (Custom Hook)"]:::hook
        WS["useWindowScroll (Custom Hook)"]:::hook
    end

    %% Subgraph: Support Files
    subgraph "Support Files"
        CONST["Constants & Configurations"]:::config
        STYLE["Styles for Cursor"]:::config
        TYPES["TypeScript Definitions"]:::config
        ENTRY2["Library Entry Point"]:::config
    end

    %% Subgraph: Development Tools
    subgraph "Development Tools"
        VITE["Vite"]:::dev
        ESLINT["ESLint"]:::dev
        PRETTIER["Prettier"]:::dev
        JEST["Jest"]:::dev
    end

    %% Relationships
    UA -->|"wraps"| MCP
    MCP -->|"manages"| CC
    ME -->|"triggers"| MCP
    HF -->|"updates"| MC
    WS -->|"updates"| MC
    ENTRY -->|"exports"| MCP
    ENTRY -->|"exports"| MC
    ENTRY -->|"exports"| ME

    MC -->|"utilizes"| CONST
    MC -->|"applies"| STYLE
    MC -->|"references"| TYPES
    ME -->|"utilizes"| CONST

    %% Development tools support
    VITE -->|"builds"| ENTRY
    ESLINT -->|"lints"| ENTRY
    PRETTIER -->|"formats"| ENTRY
    JEST -->|"tests"| ENTRY

    %% Click Events
    click MC "https://github.com/nicodos/magic-cursor/blob/main/lib/components/Cursor.tsx"
    click ME "https://github.com/nicodos/magic-cursor/blob/main/lib/components/Element.tsx"
    click CC "https://github.com/nicodos/magic-cursor/blob/main/lib/contexts/CursorContext.ts"
    click MCP "https://github.com/nicodos/magic-cursor/blob/main/lib/providers/CursorProvider.tsx"
    click HF "https://github.com/nicodos/magic-cursor/blob/main/lib/hooks/useFollowPointer.ts"
    click WS "https://github.com/nicodos/magic-cursor/blob/main/lib/hooks/useWindowScroll.ts"
    click CONST "https://github.com/nicodos/magic-cursor/blob/main/lib/constants/index.ts"
    click STYLE "https://github.com/nicodos/magic-cursor/blob/main/lib/styles/cursor.css"
    click TYPES "https://github.com/nicodos/magic-cursor/blob/main/lib/index.types.ts"
    click ENTRY "https://github.com/nicodos/magic-cursor/blob/main/lib/index.ts"

    %% Styles
    classDef ui fill:#d0eaff,stroke:#0277bd,stroke-width:2px;
    classDef provider fill:#e0f7fa,stroke:#00838f,stroke-width:2px;
    classDef hook fill:#dcedc8,stroke:#558b2f,stroke-width:2px;
    classDef config fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef dev fill:#fce4ec,stroke:#c2185b,stroke-width:2px;
```
