# vladislavkovaliov/simple-react-router architecture

> Architecture diagram of the GitHub repository vladislavkovaliov/simple-react-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vladislavkovaliov/simple-react-router
- Repository: https://github.com/vladislavkovaliov/simple-react-router

## Overview

##### Project type and purpose
- This is an open-source React component library (“Simple React Router”) that provides a minimal navigation solution via React Context and Hooks.
- Its purpose is to let downstream React applications declare screens, wrap them in a NavigatorProvider, and navigate between them using simple hook calls.

##### File structure
- Top-level files:
– package.json, tsconfig.json, vite.config.ts – TypeScript project, built with Vite, published to npm.
– src/ – your library’s source modules.
– dist/ – compiled JS output by Vite for distribution.
– types/ – handwritten or generated .d.ts definitions.
– .github/, .husky/ – CI checks and git hooks.
- src/ hierarchy:
– src/App.tsx, Home.tsx, Main.tsx – example/demo code.
– src/index.ts(x) – library entry point, re-exports hooks/providers.
– src/hooks/usePrevious.ts – internal hook to retain previous state.
– src/providers/navigator/ – core NavigatorContext, NavigatorProvider, NavigatorScreen, type definitions.
- dist/ mirrors src/ but in compiled form.

##### Key insights from the README
- The consumer wraps their app in <NavigatorProvider onScreenChange=… fallbackRouteName=…>
- They declare <NavigatorScreen name="…" component={…} props={…}/> for each route.
- Within components, they call goNextTo, goBack, reset from NavigatorContext via a custom hook.

##### Main components
a. Consumer React Application
b. NavigatorProvider
c. NavigatorContext (React.createContext)
d. NavigatorScreen registrations
e. Navigation State (screen stack)
f. Navigation Hooks: usePrevious, useContext(NavigatorContext) → goNextTo/goBack/reset
g. Build & Distribution Pipeline: Vite → dist → npm package
h. TypeScript Definitions (types/)

##### Relationships and interactions
- The Consumer App imports the library’s entry point (index.js) from npm.
- App renders <NavigatorProvider> which initializes Navigation State and exposes the context.
- App nests <NavigatorScreen> elements as children; Provider reads these to build the route registry.
- Provider uses usePrevious internally to track the previous screen for onScreenChange.
- When a component calls goNextTo/goBack/reset (via useContext), the Provider updates its state and re-renders the active screen component.
- onScreenChange callback is invoked with { currScreenName, prevScreenName } on each navigation event.

##### Architectural patterns and design principles
- Dependency Injection & Inversion of Control via React Context (Provider/Consumer)
- Hook-based encapsulation of navigation logic
- Stateless screen declarations; state managed centrally in Provider
- Single Responsibility: NavigatorProvider for state, NavigatorScreen for registration, hooks for side-effects/state tracking

##### Step-by-step diagramming guide
– NavigatorProvider
– NavigatorContext
– NavigatorScreen registry
– usePrevious hook
– navigation hooks (goNextTo/goBack/reset)
4. Provider supplying context to Screens.
5. Screens being rendered based on the Provider’s internal state (screen stack).
– import/consume (App → Library)
– register screens (App → NavigatorProvider)
– navigate (Screen Component → Provider via hook)
– build output (Vite → dist)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application
    ConsumerApp["Consumer React Application"]:::consumer
    click ConsumerApp "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/App.tsx"
    ConsumerApp -->|"imports"| EntryPoint

    %% Library Entry Point
    EntryPoint["Library Entry Point (index.ts/x)"]:::api
    click EntryPoint "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/index.ts"
    click EntryPoint "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/index.tsx"
    EntryPoint -->|"re-exports"| HooksIndex
    EntryPoint -->|"re-exports"| ProvidersBarrel

    %% Hooks and Providers Barrels
    HooksIndex["Hooks Index"]:::runtime
    click HooksIndex "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/hooks/index.ts"
    ProvidersBarrel["Providers Barrel"]:::runtime
    click ProvidersBarrel "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/providers/index.ts"
    ProvidersBarrel -->|"re-exports"| NavigatorBarrel

    %% Navigator Barrel
    NavigatorBarrel["Navigator Barrel"]:::runtime
    click NavigatorBarrel "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/providers/navigator/index.ts"
    NavigatorBarrel -->|"exposes"| NavigatorProvider
    NavigatorBarrel -->|"exposes"| NavigatorContext
    NavigatorBarrel -->|"exposes"| NavigatorScreen

    %% Runtime Components
    NavigatorProvider["NavigatorProvider"]:::runtime
    click NavigatorProvider "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/providers/navigator/NavigatorProvider.tsx"
    NavigatorContext["NavigatorContext"]:::runtime
    click NavigatorContext "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/providers/navigator/NavigatorContext.tsx"
    NavigatorScreen["NavigatorScreen"]:::runtime
    click NavigatorScreen "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/providers/navigator/NavigatorScreen.tsx"
    UsePrevious["usePrevious Hook"]:::runtime
    click UsePrevious "https://github.com/vladislavkovaliov/simple-react-router/blob/main/src/hooks/usePrevious.ts"

    %% Consumer Usage
    ConsumerApp -->|"renders"| NavigatorProvider
    ConsumerApp -->|"declares screens"| NavigatorScreen
    NavigatorProvider -->|"provides context via"| NavigatorContext
    NavigatorProvider -->|"internally uses"| UsePrevious

    %% Build & Distribution Pipeline
    ViteConfig["Vite Configuration"]:::build
    click ViteConfig "https://github.com/vladislavkovaliov/simple-react-router/blob/main/vite.config.ts"
    Dist["Dist Output"]:::build
    click Dist "https://github.com/vladislavkovaliov/simple-react-router/tree/main/dist/"
    Types["TypeScript Definitions"]:::build
    click Types "https://github.com/vladislavkovaliov/simple-react-router/tree/main/types/"
    Npm["npm Package"]:::build

    ViteConfig -->|"builds"| Dist
    ViteConfig -->|"generates"| Types
    Dist -->|"published to"| Npm
    Types -->|"published to"| Npm

    %% CI/CD and Git Hooks
    CIWorkflow["CI Workflow"]:::build
    click CIWorkflow "https://github.com/vladislavkovaliov/simple-react-router/blob/main/.github/workflows/master.yml"
    GitHooks["Git Hooks"]:::build
    click GitHooks "https://github.com/vladislavkovaliov/simple-react-router/tree/main/.husky/pre-commit"
    click GitHooks "https://github.com/vladislavkovaliov/simple-react-router/tree/main/.husky/commit-msg"

    CIWorkflow -->|"triggers build"| ViteConfig
    GitHooks -->|"enforce checks"| EntryPoint

    %% Styles
    classDef runtime fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px;
    classDef api fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px;
    classDef consumer fill:#FFF9C4,stroke:#F9A825,stroke-width:1px;
    classDef build fill:#E0E0E0,stroke:#424242,stroke-width:1px;
```
