# samuelarbibe/dnd-timeline architecture

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

- Interactive diagram: https://gitdiagram.com/samuelarbibe/dnd-timeline
- Repository: https://github.com/samuelarbibe/dnd-timeline

## Overview

##### Project type and purpose
- This is a monorepo (managed by Turborepo + pnpm) containing:
– A core “dnd-timeline” headless React library (hook-based, zero styling, built on dnd-kit)
– A set of configuration packages (config-biome, config-typescript, config-release-it)
– Multiple example/demo React apps (basic, create, external, home, performance, sortable, timeaxis, virtual)
– Documentation (docs/v1, docs/v2)
– CI/CD workflows (.github/workflows)
- Purpose: develop, test, document, and publish the dnd-timeline library while showcasing its usage via examples.

##### File structure / architectural patterns
- Top-level / root
– pnpm-workspace.yaml, turbo.json: orchestrate tasks across packages
– .github/workflows: CI pipelines for testing, building, deploying docs and examples
– docs/: static site generator input (versioned guides & API docs)
– packages/:
· config-* packages: share build/test/lint configs
· dnd-timeline: the core library (src/hooks, src/store, src/utils, src/types)
- examples/: independent React/Vite apps, each importing the local dnd-timeline package via pnpm link
- build & release: release-it configs, tsup, biome.json, commitlint, husky hooks

##### Main components
A. Monorepo Orchestrator
– Turborepo (turbo.json)
– pnpm workspace
B. Configuration Layer
– config-biome, config-typescript, config-release-it
– Shared lint/build/test configurations
C. Core Library: dnd-timeline
– src/hooks (useItem, useRow, useTimelineContext…)
– src/store (shared state management)
– src/utils (positioning, validation, pan strategies)
– Exports headless hooks + styling helpers
D. Examples (8 distinct React/Vite apps)
– Each app imports dnd-timeline and config-* via workspace links
– Uses Vite, React, custom CSS or Tailwind
– Demonstrates features: external drag, virtualization, sorting, creating, time axis, performance
E. Documentation Site
– docs/v1 & docs/v2 Markdown
– Built & deployed via CI workflows
F. CI/CD Pipelines
– .github/workflows/deploy-examples.yml (build & deploy each example)
– deploy-preview.yml, deploy-production.yml (docs site & library release)
– deploy.yml (general pipeline)

##### Relationships & interactions
- Developer changes core library → Turborepo rebuilds affected packages → local examples auto-reload
- Examples ← imports ← Core Library + config packages
- CI pipelines triggered on PR/merge → run tests/lints → build core + docs + examples → deploy
- Documentation ← Markdown source → static site generator → hosted on docs site

##### Architectural patterns / design principles
- Monorepo (single repo, many packages)
- Headless-UI library (logic-only, styling-agnostic)
- Hook-based React API (useItem, useRow, useTimelineContext)
- Task orchestration via Turborepo (filtering, incremental builds)
- Workspace linking (pnpm) for zero-install symlinking

##### Essential elements
- Packages vs. examples vs. CI pipelines vs. external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestrator Layer
    subgraph "Monorepo Orchestrator"
        direction TB
        Pnpm["pnpm workspace"]:::orchestrator
        Turborepo["Turborepo (turbo.json)"]:::orchestrator
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        ConfigBiome["config-biome"]:::config
        ConfigTS["config-typescript"]:::config
        ConfigRelease["config-release-it"]:::config
    end

    %% Core Library
    subgraph "Core Library: dnd-timeline"
        direction TB
        DNDPackage["dnd-timeline (package.json)"]:::core
        EntryPoint["src/index.tsx"]:::core
        Hooks["src/hooks/*"]:::core
        Store["src/store/Timeline.tsx"]:::core
        Utils["src/utils/*"]:::core
        Types["src/types/*"]:::core
    end

    %% Examples Layer
    subgraph "Examples"
        direction TB
        Basic["example: basic"]:::examples
        Create["example: create"]:::examples
        Demo["example: demo"]:::examples
        External["example: external"]:::examples
        Home["example: home"]:::examples
        Performance["example: performance"]:::examples
        Sortable["example: sortable"]:::examples
        TimeAxisEx["example: timeaxis"]:::examples
        Virtual["example: virtual"]:::examples
    end

    %% Documentation Site
    subgraph "Documentation Site"
        direction TB
        DocsV1["docs/v1"]:::docs
        DocsV2["docs/v2"]:::docs
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        DeployExamples["deploy-examples.yml"]:::cicd
        DeployPreview["deploy-preview.yml"]:::cicd
        DeployProduction["deploy-production.yml"]:::cicd
        DeployGeneral["deploy.yml"]:::cicd
    end

    %% External Services
    NpmRegistry[(npm registry)]:::external
    Hosting[(Vercel/Netlify)]:::external

    %% Relationships
    Pnpm -->|manages| ConfigBiome
    Pnpm -->|manages| ConfigTS
    Pnpm -->|manages| ConfigRelease
    Pnpm -->|manages| DNDPackage
    Pnpm -->|links| Basic
    Pnpm -->|links| Create
    Pnpm -->|links| Demo
    Pnpm -->|links| External
    Pnpm -->|links| Home
    Pnpm -->|links| Performance
    Pnpm -->|links| Sortable
    Pnpm -->|links| TimeAxisEx
    Pnpm -->|links| Virtual

    Turborepo -->|orchestrates builds| ConfigBiome
    Turborepo -->|orchestrates builds| ConfigTS
    Turborepo -->|orchestrates builds| ConfigRelease
    Turborepo -->|orchestrates builds| DNDPackage
    Turborepo -->|rebuilds| Basic
    Turborepo -->|rebuilds| Create
    Turborepo -->|rebuilds| Demo
    Turborepo -->|rebuilds| External
    Turborepo -->|rebuilds| Home
    Turborepo -->|rebuilds| Performance
    Turborepo -->|rebuilds| Sortable
    Turborepo -->|rebuilds| TimeAxisEx
    Turborepo -->|rebuilds| Virtual

    Basic -->|imports| DNDPackage
    Create -->|imports| DNDPackage
    Demo -->|imports| DNDPackage
    External -->|imports| DNDPackage
    Home -->|imports| DNDPackage
    Performance -->|imports| DNDPackage
    Sortable -->|imports| DNDPackage
    TimeAxisEx -->|imports| DNDPackage
    Virtual -->|imports| DNDPackage

    Basic -->|imports| ConfigBiome
    Create -->|imports| ConfigTS
    Demo -->|imports| ConfigRelease

    DocsV1 -->|source| DocsV2
    DocsV1 -->|build| Hosting
    DocsV2 -->|build| Hosting

    DeployExamples -->|build/deploy| Basic
    DeployExamples -->|build/deploy| Create
    DeployExamples -->|build/deploy| Demo
    DeployExamples -->|build/deploy| External
    DeployExamples -->|build/deploy| Home
    DeployExamples -->|build/deploy| Performance
    DeployExamples -->|build/deploy| Sortable
    DeployExamples -->|build/deploy| TimeAxisEx
    DeployExamples -->|build/deploy| Virtual
    DeployExamples -->|host| Hosting

    DeployPreview -->|build/docs| DocsV1
    DeployProduction -->|build/docs| DocsV2
    DeployGeneral -->|release| NpmRegistry
    DeployGeneral -->|publish| DNDPackage

    %% Click Events
    click Pnpm "https://github.com/samuelarbibe/dnd-timeline/blob/main/pnpm-workspace.yaml"
    click Turborepo "https://github.com/samuelarbibe/dnd-timeline/blob/main/turbo.json"
    click ConfigBiome "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/config-biome/biome.json"
    click ConfigTS "https://github.com/samuelarbibe/dnd-timeline/tree/main/packages/config-typescript/"
    click ConfigRelease "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/config-release-it/index.js"
    click DNDPackage "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/dnd-timeline/package.json"
    click EntryPoint "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/dnd-timeline/src/index.tsx"
    click Hooks "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/dnd-timeline/src/hooks/useItem.tsx"
    click Store "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/dnd-timeline/src/store/Timeline.tsx"
    click Utils "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/dnd-timeline/src/utils/index.ts"
    click Types "https://github.com/samuelarbibe/dnd-timeline/blob/main/packages/dnd-timeline/src/types/index.ts"
    click Basic "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/basic/"
    click Create "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/create/"
    click Demo "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/demo/"
    click External "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/external/"
    click Home "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/home/"
    click Performance "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/performance/"
    click Sortable "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/sortable/"
    click TimeAxisEx "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/timeaxis/"
    click Virtual "https://github.com/samuelarbibe/dnd-timeline/tree/main/examples/virtual/"
    click DocsV1 "https://github.com/samuelarbibe/dnd-timeline/tree/main/docs/v1/"
    click DocsV2 "https://github.com/samuelarbibe/dnd-timeline/tree/main/docs/v2/"
    click DeployExamples "https://github.com/samuelarbibe/dnd-timeline/blob/main/.github/workflows/deploy-examples.yml"
    click DeployPreview "https://github.com/samuelarbibe/dnd-timeline/blob/main/.github/workflows/deploy-preview.yml"
    click DeployProduction "https://github.com/samuelarbibe/dnd-timeline/blob/main/.github/workflows/deploy-production.yml"
    click DeployGeneral "https://github.com/samuelarbibe/dnd-timeline/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef orchestrator fill:#cce5ff,stroke:#004085,color:#004085;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef examples fill:#fff3cd,stroke:#856404,color:#856404;
    classDef docs fill:#e2d6f3,stroke:#5a2a83,color:#5a2a83;
    classDef cicd fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
