# enszrlu/nextstep architecture

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

- Interactive diagram: https://gitdiagram.com/enszrlu/nextstep
- Repository: https://github.com/enszrlu/nextstep

## Overview

##### Main Components
- Core library components:
- NextStep: The central component that manages the tour process and rendering.
- NextStepProvider/NextStepContext: Provides context/state management for the tour.
- useNextStep: A hook to start, close, or control the tour from within the application.
- Tour configuration:
- Customization components:
- Custom Card components to render tour tooltips.
- NextStepViewport: Wrapping scrollable content to ensure steps target the right viewport.

##### Navigation Adapters
- The project includes an adapters directory both under src and in the built dist folder.
- Adapters for:
- Next.js (default behavior).
- React Router.
- Remix.
- Window adapter (fallback for non-framework specific navigation).
- These adapters abstract navigation actions such as push, getCurrentPath, and allow custom implementations.

##### Relationships and Data Flow
- The application that uses NextStep will wrap its components in a NextStepProvider so that the core NextStep component can access the tour configuration and manage global state.
- During a tour, events like onStepChange, onComplete, and onSkip are triggered and can be hooked by developers.
- The NextStep component interacts with the navigation adapter (provided either as default in Next.js or via a custom adapter) to perform route navigation when a step specifies nextRoute or prevRoute.
- The useNextStep hook allows UI triggers (buttons, events) to initiate or manipulate a tour.

##### Architectural Patterns and Design Principles
- Modularity: Different directories for source code (src) and build output (dist) demonstrate clear separation between development and production artifacts.
- Adapter Pattern: The use of navigation adapters for various frameworks indicates dynamic binding of routing logic.
- Component-Based UI: By exposing customizable components (like CustomCard) and viewports, it follows common React component patterns.
- Event-Driven Communication: Hooks and callback props (onStepChange, onComplete, onSkip) create an event-driven system for managing tours.

##### Relevant Technologies and Tools
- TypeScript is used throughout the code (as indicated by .ts and .tsx files).
- Motion (from the motion.dev library) is used for animations.
- React as the main UI framework.
- The provided configuration for Vite and the specific export settings for Next.js (ES Modules) must also be captured since they impact deployment/integration.

##### Instructing the Principal Software Engineer
1. Application Integration Layer: Show where in the user’s app the NextStepProvider is applied and where the NextStep component is rendered.
4. Tour Configuration & Customization: Include a “Tour Steps” component block detailing the structure of a tour (steps, selectors, routing), along with configurable Custom Card and NextStepViewport.
– Data flow (for example, “tour config”, “navigation actions”, “state/event callbacks”).
– Dependencies (e.g., “uses”, “calls”, “implements”).
- Using annotations to explain the function of each component, choices of routing adapters, and how customization points (like custom cards and viewports) are injected.

This detailed, component-by-component breakdown ensures clarity about which elements belong to the core library, which provide integration points (adapters), and which allow user customization. This comprehensive map helps in both debugging the flow and understanding how to extend or modify the onboarding experience.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Integration Layer
    subgraph "Application Integration Layer"
        A["User Application"]:::integration
        NP["NextStepProvider/NextStepContext"]:::core
    end

    %% Core Library
    subgraph "Core Library"
        NS["NextStep"]:::core
        NN["useNextStep"]:::core
    end

    %% Navigation Adapters
    subgraph "Navigation Adapters"
        AD_Next["Next.js Adapter"]:::adapter
        AD_RR["React Router Adapter"]:::adapter
        AD_Remix["Remix Adapter"]:::adapter
        AD_Window["Window Adapter"]:::adapter
    end

    %% Tour Configuration & Customization
    subgraph "Tour Configuration & Customization"
        TC["Tour Steps"]:::config
        CC["Custom Card"]:::custom
        VP["NextStepViewport"]:::custom
    end

    %% Relationships and Data Flow
    A -->|"wraps"| NP
    NP -->|"provides context to"| NS
    NP -->|"injects config"| TC
    NS -->|"uses-hook"| NN
    NN -->|"triggers tour"| NS
    TC -->|"configures"| NS
    NS -->|"renders tooltip via"| CC
    NS -->|"ensures proper viewport"| VP
    NS -->|"default routing action"| AD_Next
    NS -->|"optional routing"| AD_RR
    NS -->|"optional routing"| AD_Remix
    NS -->|"fallback routing"| AD_Window

    %% Click Events
    click NS "https://github.com/enszrlu/nextstep/blob/main/src/NextStep.tsx"
    click NP "https://github.com/enszrlu/nextstep/blob/main/src/NextStepContext.tsx"
    click NN "https://github.com/enszrlu/nextstep/blob/main/src/NextStepReact.tsx"
    click CC "https://github.com/enszrlu/nextstep/blob/main/src/DefaultCard.tsx"
    click VP "https://github.com/enszrlu/nextstep/blob/main/src/NextStepViewport.tsx"
    click AD_Next "https://github.com/enszrlu/nextstep/tree/main/src/adapters/next"
    click AD_RR "https://github.com/enszrlu/nextstep/tree/main/src/adapters/react-router"
    click AD_Remix "https://github.com/enszrlu/nextstep/tree/main/src/adapters/remix"
    click AD_Window "https://github.com/enszrlu/nextstep/tree/main/src/adapters/window"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef adapter fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef custom fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef integration fill:#FFF9C4,stroke:#333,stroke-width:2px;
    classDef config fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
