# vtex/shoreline architecture

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

- Interactive diagram: https://gitdiagram.com/vtex/shoreline
- Repository: https://github.com/vtex/shoreline

## Overview

##### Project Type and Purpose
- This is a monorepo hosting Shoreline, a React-based design system and toolkit for building VTEX Admin apps.
- It comprises multiple npm packages (component library, CSS tokens, utility functions, test utilities, table package, documentation site), orchestrated by pnpm, Lerna, and Turborepo.

##### File Structure Analysis
- Top-level files and folders:
- pnpm-workspace.yaml, lerna.json, turbo.json → workspace orchestration and fast build.
- .github/workflows → CI pipelines for PR checks, tests, publishing.
- .husky, commitlint.config.js → Git hooks & commit standards.
- storybook/, vite.config.ts → Storybook config for live component previews.
- scripts/, plopfile.js → scaffolding and maintenance scripts.
- packages/ → each subfolder is an independent published module:
- css → design tokens, generation of CSS bundles (tsup, build scripts).
- shoreline → the core React component library with stories, tests, theming.
- docs → Next.js + MDX site for API reference, guides, and live examples.
- test-utils → shared testing utilities (Vitest, React helpers).
- ts-table → specialized table component package.
- utils → shared TypeScript utilities.
- Dependencies flow:
utils + css → shoreline + ts-table → docs + storybook. test-utils serves shoreline and ts-table tests.

a. Main Components
- Developer Workstation (CLI tools: pnpm, plop)
- Monorepo Orchestrator (pnpm/Lerna/Turbo)
- Package Modules: css, utils, test-utils, ts-table, shoreline
- Documentation Site (Next.js/MDX)
- Storybook Server (Vite/React)
- CI/CD (GitHub Actions)
- npm Registry (publishing target)
- External Consumers (VTEX Admin Apps)
b. Relationships & Data Flow
- Developer invokes build/dev commands via pnpm CLI → Orchestrator schedules builds across packages.
- css builds design tokens → shoreline & ts-table import CSS bundles.
- utils provides shared functions → all code packages import it.
- test-utils supplies test helpers → shoreline & ts-table tests import.
- shoreline & ts-table exports → Storybook for live component rendering & Next.js docs site for examples/docs.
- CI triggers on push/PR → runs tests, lint, build, then publishes to npm and deploys docs.
- External VTEX Admin apps fetch published packages from npm.
c. Architectural Patterns & Principles
- Monorepo with package isolation and sharing.
- Workspace dependency graph for incremental builds (Turborepo).
- Micro-library decomposition: each concern (styling, components, utilities, docs) is a separate package.
- CI/CD as code via GitHub Actions.
- Component-driven development with Storybook.
d. Key Technologies
- pnpm, Lerna, Turborepo for workspace management and incremental builds.
- TypeScript, React, MDX/Next.js for code and docs.
- Vite & Storybook for live component preview.
- tsup for bundling.
- Vitest for testing.
- GitHub Actions for CI/CD.

##### Essential Details to Capture
- Monorepo orchestrator at root controlling per-package lifecycle.
- Package boundary and reuse: css → shoreline, utils → all, test-utils → tests, ts-table → standalone table.
- Two developer-facing servers: Storybook for components and Next.js for docs.
- CI/CD flow from GitHub Actions to npm Registry and docs deployment.
- External consumption by VTEX Admin applications.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration & CI Layer
    DevWS["Developer Workstation\n(CLI & Scripts)"]:::orchestration
    Orchestrator["Monorepo Orchestrator\n(pnpm/Lerna/Turbo)"]:::orchestration
    CI["CI/CD (GitHub Actions)"]:::orchestration

    %% Package Modules
    subgraph "packages"
        CSS["CSS Tokens\nPackage"]:::library
        Utils["Utility Functions\nPackage"]:::library
        TestUtils["Test Utilities\nPackage"]:::library
        TsTable["Table Component\nPackage (ts-table)"]:::library
        Shoreline["Core React Component\nLibrary (shoreline)"]:::library
        DocsPkg["Documentation Site\n(Next.js + MDX)"]:::library
    end

    %% Developer-facing Servers
    Storybook["Storybook Server\n(Vite & React)"]:::devserver
    DocsSite["Docs Site\n(Next.js)"]:::devserver

    %% Publishing & Consumption
    Registry["npm Registry\n(Publishing Target)"]:::external
    External["VTEX Admin Apps\n(Consumers)"]:::external

    %% Relationships
    DevWS -->|"invokes build/dev"| Orchestrator
    Orchestrator -->|"schedules builds"| CSS
    Orchestrator -->|"schedules builds"| Utils
    Orchestrator -->|"schedules builds"| TestUtils
    Orchestrator -->|"schedules builds"| TsTable
    Orchestrator -->|"schedules builds"| Shoreline
    Orchestrator -->|"schedules builds"| DocsPkg

    CSS -->|"imports CSS bundles"| Shoreline
    CSS -->|"imports CSS bundles"| TsTable
    Utils -->|"imports utilities"| Shoreline
    Utils -->|"imports utilities"| TsTable
    Utils -->|"imports utilities"| DocsPkg
    Utils -->|"imports utilities"| Storybook
    TestUtils -->|"provides test helpers"| Shoreline
    TestUtils -->|"provides test helpers"| TsTable

    Shoreline -->|"renders components"| Storybook
    TsTable -->|"renders table examples"| Storybook
    Shoreline -->|"provides examples"| DocsSite
    TsTable -->|"provides examples"| DocsSite
    CSS -->|"provides tokens"| DocsSite

    CI -->|"runs tests/lint/build"| Orchestrator
    CI -->|"publishes packages"| Registry
    CI -->|"deploys docs"| DocsSite

    Registry -->|"installs packages"| External

    %% Click Events
    click DevWS "https://github.com/vtex/shoreline/blob/main/plopfile.js"
    click DevWS "https://github.com/vtex/shoreline/tree/main/scripts/"
    click DevWS "https://github.com/vtex/shoreline/tree/main/templates/"
    click Orchestrator "https://github.com/vtex/shoreline/blob/main/pnpm-workspace.yaml"
    click Orchestrator "https://github.com/vtex/shoreline/blob/main/lerna.json"
    click Orchestrator "https://github.com/vtex/shoreline/blob/main/turbo.json"
    click CI "https://github.com/vtex/shoreline/blob/main/.github/workflows/pr.yml"
    click CI "https://github.com/vtex/shoreline/blob/main/.github/workflows/release.yml"
    click Storybook "https://github.com/vtex/shoreline/tree/main/.storybook/"
    click Storybook "https://github.com/vtex/shoreline/blob/main/vite.config.ts"
    click CSS "https://github.com/vtex/shoreline/tree/main/packages/css/"
    click Utils "https://github.com/vtex/shoreline/tree/main/packages/utils/"
    click TestUtils "https://github.com/vtex/shoreline/tree/main/packages/test-utils/"
    click TsTable "https://github.com/vtex/shoreline/tree/main/packages/ts-table/"
    click Shoreline "https://github.com/vtex/shoreline/tree/main/packages/shoreline/"
    click DocsSite "https://github.com/vtex/shoreline/tree/main/packages/docs/"
    click Registry "https://github.com/vtex/shoreline/blob/main/.npmrc"

    %% Styles
    classDef orchestration fill:#f9f,stroke:#333,stroke-width:1px;
    classDef library fill:#bbf,stroke:#333,stroke-width:1px;
    classDef devserver fill:#bfb,stroke:#333,stroke-width:1px;
    classDef external fill:#ffb,stroke:#333,stroke-width:1px;
```
