# dai-shi/react-tracked architecture

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

- Interactive diagram: https://gitdiagram.com/dai-shi/react-tracked
- Repository: https://github.com/dai-shi/react-tracked

## Overview

##### Project type and purpose
- This is an open-source React library (“React Tracked”) that provides “state usage tracking” via Proxies to optimize component re‐renders.
- It ships two core APIs: `createContainer` (for custom hook containers) and `createTrackedSelector` (for selectors over Redux, Zustand, etc.).

##### File structure
- Top-level:
- Configuration & CI: `.github/workflows/`, `vite.config.ts`, multiple `tsconfig.*.json`, `package.json`, lockfiles, lint/prettier configs.
- Core library: `src/` (contains `createContainer.ts`, `createTrackedSelector.ts`, `index.ts`, `utils.ts`).
- Examples: `examples/01_*` through `examples/15_*`—each a standalone minimal React app demonstrating use cases.
- Tests:
– Unit & snapshot tests in `tests/` using Vitest.
– E2E tests in `tests/e2e/` (Playwright or similar).
- Documentation website: `website/`—a Docusaurus site with custom modules, docs, pages, and static assets.

##### README for additional insights
- The README describes the library’s goals, usage patterns (two APIs), integration with React, Redux, Zustand, and notes on React-18 behavior.
- It links to API docs, recipes, tutorials, and examples.

a. Main components
1. Core Library Module
- `createContainer` API
- `createTrackedSelector` API
- Core tracking engine (Proxy‐based change detector) in `utils.ts`
2. Consumer Examples
- 15 example apps showing incremental features—from counter to advanced hooks.
3. Documentation Website
- Docusaurus front end serving markdown docs, API reference, tutorials.
- Custom remark plugin (`website/custom_modules/docusaurus-remark-plugin-ts2js`).
4. Test Suites
- Unit tests (Vitest)
- E2E tests (Playwright/TS)
5. Build & CI/CD
- Vite build of library and examples
- Vitest workspace setup
- GitHub Actions for CI (lint, tests) and CD (publish to npm, deploy website)
6. External Dependencies
- React, React‐Redux, Zustand, use‐context‐selector, scheduler

b. Relationships & interactions
- The Core Library is the heart; it’s built by Vite, shipped to npm.
- Examples import the built (or local) core library to demonstrate API usage.
- The Documentation Website bundles the library’s API docs and live code samples (often pointing to examples).
- Tests import directly from `src/` to validate behavior.
- CI workflows trigger builds, tests, and website deployments upon commits.
- End users consume the published package via npm and integrate with React apps.

c. Architectural patterns & design principles
- Modular layering: Core engine → API wrappers → Consumer code
- Separation of concerns: examples/test/site each in own directory
- Plugin architecture in docs (custom remark plugin)
- Declarative CI/CD pipelines (GitHub Actions)

d. Key technologies & frameworks
- TypeScript + Vite for library building
- Vitest for unit/snapshot testing
- Playwright (or similar) for E2E tests
- Docusaurus v2 for docs website
- React hooks + Proxies for tracking
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        direction TB
        CL_Index["index.ts"]:::core
        CC["createContainer.ts"]:::core
        CTS["createTrackedSelector.ts"]:::core
        UTILS["utils.ts"]:::core
    end

    %% Examples
    subgraph "Examples"
        direction TB
        EX["15 incremental React apps"]:::examples
    end

    %% Documentation Website
    subgraph "Documentation Website"
        direction TB
        DOC["Docusaurus Site"]:::docs
        PLUGIN["custom_plugins/ts2js"]:::docs
    end

    %% Tests
    subgraph "Tests"
        direction TB
        UT["Unit Tests (Vitest)"]:::tests
        ET["E2E Tests (Playwright)"]:::tests
    end

    %% CI/CD
    subgraph "CI/CD & Build"
        direction TB
        VITE["vite.config.ts"]:::cicd
        CI["GitHub Actions CI"]:::cicd
        CD["GitHub Actions CD"]:::cicd
    end

    %% External Dependencies & Services
    subgraph "External"
        direction TB
        REACT["React, Redux, Zustand, etc."]:::external
        NPM["npm Registry"]:::external
        GITHUB["GitHub"]:::external
    end

    %% Relationships
    CI -->|"runs build"| VITE
    VITE -->|"bundles"| CL_Index
    CL_Index -->|"exports"| CC
    CL_Index -->|"exports"| CTS
    CC -->|"uses Proxy engine"| UTILS
    CTS -->|"uses Proxy engine"| UTILS

    CL_Index -->|"import"| EX
    CL_Index -->|"import"| DOC
    CL_Index -->|"import"| UT
    CL_Index -->|"import"| ET

    CI -->|"runs tests"| UT
    CI -->|"runs tests"| ET
    CI -->|"on push/tag"| CD
    CD -->|"publish"| NPM
    CD -->|"deploy site"| GITHUB

    EX -->|"demonstrates APIs"| CL_Index
    DOC -->|"includes live samples"| EX
    DOC -->|"uses custom plugin"| PLUGIN

    EX -->|"requires"| REACT
    CL_Index -->|"peerDeps"| REACT

    %% Click Events
    click CL_Index "https://github.com/dai-shi/react-tracked/blob/main/src/index.ts"
    click CC "https://github.com/dai-shi/react-tracked/blob/main/src/createContainer.ts"
    click CTS "https://github.com/dai-shi/react-tracked/blob/main/src/createTrackedSelector.ts"
    click UTILS "https://github.com/dai-shi/react-tracked/blob/main/src/utils.ts"
    click VITE "https://github.com/dai-shi/react-tracked/blob/main/vite.config.ts"
    click UT "https://github.com/dai-shi/react-tracked/tree/main/tests/"
    click ET "https://github.com/dai-shi/react-tracked/tree/main/tests/e2e/"
    click CI "https://github.com/dai-shi/react-tracked/blob/main/.github/workflows/ci.yml"
    click CD "https://github.com/dai-shi/react-tracked/blob/main/.github/workflows/cd.yml"
    click EX "https://github.com/dai-shi/react-tracked/tree/main/examples/"
    click DOC "https://github.com/dai-shi/react-tracked/tree/main/website/"
    click PLUGIN "https://github.com/dai-shi/react-tracked/tree/main/website/custom_modules/docusaurus-remark-plugin-ts2js"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#2f5597,color:#0f1c2e
    classDef examples fill:#d9ead3,stroke:#38761d,color:#0f1c2e
    classDef docs fill:#ffe6cc,stroke:#e69138,color:#0f1c2e
    classDef tests fill:#f4cccc,stroke:#a61c20,color:#0f1c2e
    classDef cicd fill:#ead1dc,stroke:#741b47,color:#0f1c2e
    classDef external fill:#dddddd,stroke:#666666,color:#0f1c2e
```
