# vlddlv/react-text-annotation architecture

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

- Interactive diagram: https://gitdiagram.com/vlddlv/react-text-annotation
- Repository: https://github.com/vlddlv/react-text-annotation

## Overview

##### Project Type & Purpose
- This is an **open-source React UI component library** (Text Annotator) written in TypeScript.
- It exports a set of React components and helper functions for annotating text, published to npm and demonstrated via a Next.js “example” app and a GitHub Pages live demo.

##### Key Architectural Components
a. **Source Code**
- `src/` folder:
- `components/`: `Mark.tsx`, `Splitter.tsx`, `TextWrapper.tsx` + their tests
- `functions.tsx`: core annotation logic + tests
- `index.tsx`: entry‐point exporting all APIs
- **Configuration & Tooling**
- `tsconfig.json`, `eslint.config.js`
- Build scripts in `package.json` (e.g. `build`, `test`)
b. **Build / CI**
- Transpile & bundle: `src/` → `dist/` (`.js` + `.d.ts`)
- Linting & testing (Jest/TS)
- GitHub Actions workflow (`.github/workflows/deploy.yml`) for CI & npm publishing
c. **Distribution**
- `dist/`: compiled component library, ready for consumers
- `package.json`: metadata, dependencies, bundler configuration
d. **Demo / Example Application**
- `example/`: Next.js-based demo site showcasing usage
- `app/`: Next.js `layout.tsx`, `page.tsx`, Tailwind CSS config, etc.
- Demonstrates how a downstream project imports `react-text-annotation`
e. **Publishing / Hosting**
- npm registry (versioned releases)
- GitHub Pages for “Live Demo”

##### Relationships & Data Flows
- **Developers** write & maintain code in `src/`.
- **CI Pipeline** runs tests & lints, then builds into `dist/`.
- **npm Publish** pushes `dist/` to npm.
- **Consumers** (e.g. any React/Next.js app, the `example/` site) install from npm and import the components.
- **Demo Hosting**: example code is built & deployed to GH Pages.

##### Architectural Patterns & Design Principles
- **Modular Design**: each UI piece in its own component + reusable functions
- **Single Responsibility**: components only handle rendering & selection logic; `functions.tsx` handles core annotation algorithms
- **Distribution Pipeline**: clear separation of source (`src/`) vs. build output (`dist/`)
- **CI/CD**: automated testing, building, publishing, and demo deployment

##### Essential Elements
- src/components
- src/functions
- src/index (public API)
- **Build & Test**:
- ESLint, Jest
- GitHub Actions (`deploy.yml`)
- **Distribution**: `dist/`
- **Publish**: npm registry
- **Consumption**: example app (Next.js + Tailwind / Styled Components)
- **Hosting**: GitHub Pages live demo

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Code Layer
    subgraph "Source Code" 
        direction TB
        src_components["src/components"]:::code
        src_functions["src/functions.tsx"]:::code
        src_index["src/index.tsx"]:::code
        tsconfig["tsconfig.json"]:::code
        eslint_cfg["eslint.config.js"]:::code
        subgraph "Component Files & Tests"
            direction TB
            mark["Mark.tsx"]:::code
            splitter["Splitter.tsx"]:::code
            textwrapper["TextWrapper.tsx"]:::code
            mark_test["Mark.test.tsx"]:::code
            splitter_test["Splitter.test.tsx"]:::code
            textwrapper_test["TextWrapper.test.tsx"]:::code
        end
        functions_test["functions.test.tsx"]:::code
    end

    %% CI / Build Layer
    subgraph "Build & CI" 
        direction TB
        eslint["ESLint"]:::pipeline
        jest["Jest"]:::pipeline
        gha["GitHub Actions"]:::pipeline
    end

    %% Distribution Package
    subgraph "Distribution" 
        direction TB
        dist_components["dist/components"]:::dist
        dist_functions["dist/functions.js"]:::dist
        dist_index_js["dist/index.js"]:::dist
        dist_index_dts["dist/index.d.ts"]:::dist
        pkgjson["package.json"]:::dist
    end

    %% Publish & External
    npm_registry["npm Registry"]:::external
    gh_pages["GitHub Pages"]:::external

    %% Demo / Example Application
    subgraph "Demo / Example App (example/)" 
        direction TB
        example_root["example/"]:::demo
        subgraph "Next.js App" 
            direction TB
            app_dir["example/app"]:::demo
            layout["layout.tsx"]:::demo
            page["page.tsx"]:::demo
            tailwind_cfg["tailwind.config.ts & app/tailwind/page.js"]:::demo
            example_pkg["example/package.json & tsconfig.json"]:::demo
            next_cfg["example/next.config.mjs"]:::demo
        end
    end

    %% Flows
    src_components -->|imports| mark
    src_components --> splitter
    src_components --> textwrapper
    src_functions --> functions_test
    src_index --> src_components
    src_index --> src_functions

    src_components --> eslint
    src_functions --> eslint
    src_index --> eslint
    eslint --> jest
    jest --> gha

    gha -->|build| dist_components
    gha --> dist_functions
    gha --> dist_index_js
    gha --> dist_index_dts
    gha --> pkgjson

    dist_components --> npm_registry
    dist_functions --> npm_registry
    dist_index_js --> npm_registry
    dist_index_dts --> npm_registry
    pkgjson --> npm_registry

    npm_registry --> example_root
    example_root --> app_dir
    app_dir --> layout
    app_dir --> page
    app_dir --> tailwind_cfg
    example_root --> example_pkg
    example_root --> next_cfg

    example_root -->|deploy demo| gh_pages

    %% Click Events
    click src_components "https://github.com/vlddlv/react-text-annotation/tree/main/src/components"
    click mark "https://github.com/vlddlv/react-text-annotation/blob/main/src/components/Mark.tsx"
    click splitter "https://github.com/vlddlv/react-text-annotation/blob/main/src/components/Splitter.tsx"
    click textwrapper "https://github.com/vlddlv/react-text-annotation/blob/main/src/components/TextWrapper.tsx"
    click mark_test "https://github.com/vlddlv/react-text-annotation/blob/main/src/components/Mark.test.tsx"
    click splitter_test "https://github.com/vlddlv/react-text-annotation/blob/main/src/components/Splitter.test.tsx"
    click textwrapper_test "https://github.com/vlddlv/react-text-annotation/blob/main/src/components/TextWrapper.test.tsx"
    click src_functions "https://github.com/vlddlv/react-text-annotation/blob/main/src/functions.tsx"
    click functions_test "https://github.com/vlddlv/react-text-annotation/blob/main/src/functions.test.tsx"
    click src_index "https://github.com/vlddlv/react-text-annotation/blob/main/src/index.tsx"
    click tsconfig "https://github.com/vlddlv/react-text-annotation/blob/main/tsconfig.json"
    click eslint_cfg "https://github.com/vlddlv/react-text-annotation/blob/main/eslint.config.js"
    click gha "https://github.com/vlddlv/react-text-annotation/blob/main/.github/workflows/deploy.yml"
    click dist_components "https://github.com/vlddlv/react-text-annotation/blob/main/dist/components/Mark.js"
    click dist_components "https://github.com/vlddlv/react-text-annotation/blob/main/dist/components/Splitter.js"
    click dist_components "https://github.com/vlddlv/react-text-annotation/blob/main/dist/components/TextWrapper.js"
    click dist_functions "https://github.com/vlddlv/react-text-annotation/blob/main/dist/functions.js"
    click dist_index_js "https://github.com/vlddlv/react-text-annotation/blob/main/dist/index.js"
    click dist_index_dts "https://github.com/vlddlv/react-text-annotation/blob/main/dist/index.d.ts"
    click pkgjson "https://github.com/vlddlv/react-text-annotation/blob/main/package.json"
    click example_root "https://github.com/vlddlv/react-text-annotation/tree/main/example/"
    click app_dir "https://github.com/vlddlv/react-text-annotation/tree/main/example/app"
    click layout "https://github.com/vlddlv/react-text-annotation/blob/main/example/app/layout.tsx"
    click page "https://github.com/vlddlv/react-text-annotation/blob/main/example/app/page.tsx"
    click tailwind_cfg "https://github.com/vlddlv/react-text-annotation/blob/main/example/tailwind.config.ts"
    click example_pkg "https://github.com/vlddlv/react-text-annotation/blob/main/example/package.json"
    click example_pkg "https://github.com/vlddlv/react-text-annotation/blob/main/example/tsconfig.json"
    click next_cfg "https://github.com/vlddlv/react-text-annotation/blob/main/example/next.config.mjs"

    %% Styles
    classDef code fill:#cfe2f3,stroke:#6fa8dc,color:#034a84
    classDef pipeline fill:#d9ead3,stroke:#93c47d,color:#274e13
    classDef dist fill:#fce5cd,stroke:#f6b26b,color:#783f04
    classDef demo fill:#e4d3f1,stroke:#b4a7d6,color:#532e63
    classDef external fill:#f4cccc,stroke:#e06666,color:#912d2b
```
