# segmentio/evergreen architecture

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

- Interactive diagram: https://gitdiagram.com/segmentio/evergreen
- Repository: https://github.com/segmentio/evergreen

## Overview

##### Project type and purpose
- This is a monorepo React UI component library and design system (“Evergreen”) maintained by Segment.
- It ships polished, enterprise-grade React components, a theming layer, codemods for migrations, a Storybook and a Next.js-based documentation site, plus an SSR example.

##### File structure
- Top-level modules:
- src/… → dozens of component packages (alert, button, dialog, etc.) each with source, tests, and Storybook stories
- themes/ & src/theme → default theme tokens, ThemeContext, theme tools
- codemods/ → jscodeshift scripts for automated version migrations
- docs/ → Next.js documentation site, MDX content, static assets, custom UI components
- examples/ssr-next → Next.js example demonstrating SSR/hydration
- rollup.config.js, tsconfig*.json, package.json → bundling and monorepo configuration
- CI/CD: GitHub Actions (ci.yml) runs tests, linting, build, Storybook deploys.

##### README insights
- Encourages contributions, has detailed docs, uses Storybook and Next.js.

- Monorepo Root
- Build & Tooling
- Rollup bundler
- TypeScript compiler
- Code generators (tools/)
- Component Layer
- Evergreen components (src/**)
- Theme library (src/theme & themes/)
- Hooks & utils (src/hooks, src/lib)
- Migration Layer
- Codemods (codemods/)
- Documentation Layer
- Storybook (src/**/stories & .storybook/)
- Next.js site (docs/)
- Example Applications
- SSR Next.js example (examples/ssr-next)
- CI/CD & Publishing
- GitHub Actions (ci.yml)
- NPM registry (evergreen-ui package)
- GitHub Pages / Vercel for docs

- Source → Build & Tooling → lib/ (CJS/ESM/UMD outputs)
- lib/ → NPM Registry (publish)
- src/** → Storybook renderer → .storybook UI
- docs/ imports built components → Next.js → static site generation
- examples/ssr-next imports evergreen-ui → demonstrates SSR
- codemods consume source code → output transformed code for migrations
- CI pipeline triggered on push → runs tests (src/** & codemods), lints, builds, deploys docs

c. Architectural patterns & principles:
- Monorepo multi-package with a shared build pipeline
- Theming via React context & CSS-in-JS
- Automated migrations via codemods
- Documentation as first-class (Storybook + Next.js + MDX)
- CI/CD for quality and publishing

d. Key technologies & frameworks:
- Rollup, TypeScript
- jscodeshift (codemods)
- Storybook, Next.js, MDX
- Jest + Testing Library
- GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root
    subgraph "Monorepo Root"
        root_pkg["package.json"]:::code
        rollup["rollup.config.js"]:::code
        tsconfig1["tsconfig.json"]:::code
        tsconfig2["tsconfig.commonjs.json"]:::code
        tsconfig3["tsconfig.types.json"]:::code
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        tools["tools/"]:::code
        babelrc[".babelrc"]:::code
        eslint[".eslintrc.json"]:::code
        prettier[".prettierignore"]:::code
        workflows[".github/workflows/ci.yml"]:::service
        storybook_cfg[".storybook/"]:::code
    end

    %% Component Layer
    subgraph "Component Layer"
        subgraph "Evergreen React Components"
            alert_pkg["src/alert/"]:::code
            buttons_pkg["src/buttons/"]:::code
            dialog_pkg["src/dialog/"]:::code
        end
        ui_box_ser["lib/testing/ui-box-snapshot-serializer.js"]:::code
        subgraph "Theme Library"
            theme_src["src/theme/"]:::code
            themes_default["src/themes/default/"]:::code
            themes_index["src/themes/index.js"]:::code
        end
        hooks["src/hooks/"]:::code
        utils["src/lib/"]:::code
        subgraph Icons
            icons_gen["src/icons/generated/"]:::code
            icon_src["src/icons/src/Icon.js"]:::code
            icon_wrapper["src/icons/src/IconWrapper.js"]:::code
            icons_index["src/icons/index.js"]:::code
        end
    end

    %% Migration Layer
    subgraph "Migration Layer"
        codemods["codemods/"]:::code
    end

    %% Documentation Layer
    subgraph "Documentation Layer"
        sb_stories["src/**/stories/"]:::docs
        next_docs["docs/"]:::docs
    end

    %% Example Applications
    examples["examples/ssr-next/"]:::code

    %% CI/CD & Publishing
    workflows --> tests[/"Tests & Lint"/]:::service
    workflows --> build[/"Build & Bundle"/]:::service
    workflows --> deploy_docs[/"Deploy Docs"/]:::service
    publish["NPM Registry"]:::service
    vercel["Vercel/GitHub Pages"]:::service

    %% Relationships
    root_pkg -->|configures| tools
    root_pkg -->|configures| rollup
    root_pkg -->|configures| tsconfig1
    tools -->|generates code for| alert_pkg
    tools -->|generates code for| icons_gen
    alert_pkg -->|built by| build
    buttons_pkg -->|built by| build
    dialog_pkg -->|built by| build
    build --> lib_out[/"lib/ CJS/ESM outputs"/]:::code
    lib_out -->|published to| publish
    publish -->|available for| examples
    codemods -->|transform| alert_pkg
    codemods -->|transform| buttons_pkg
    sb_stories -->|rendered by| storybook_cfg
    storybook_cfg -->|deployed by| workflows
    next_docs -->|imports built| lib_out
    next_docs -->|deployed to| vercel
    examples -->|imports| publish
    workflows -->|runs| codemods

    %% Click Events
    click root_pkg "https://github.com/segmentio/evergreen/blob/master/package.json (root)"
    click rollup "https://github.com/segmentio/evergreen/blob/master/rollup.config.js"
    click tsconfig1 "https://github.com/segmentio/evergreen/blob/master/tsconfig.json"
    click tsconfig2 "https://github.com/segmentio/evergreen/blob/master/tsconfig.commonjs.json"
    click tsconfig3 "https://github.com/segmentio/evergreen/blob/master/tsconfig.types.json"
    click tools "https://github.com/segmentio/evergreen/tree/master/tools/"
    click babelrc "https://github.com/segmentio/evergreen/blob/master/.babelrc"
    click eslint "https://github.com/segmentio/evergreen/blob/master/.eslintrc.json"
    click prettier "https://github.com/segmentio/evergreen/blob/master/.prettierignore"
    click workflows "https://github.com/segmentio/evergreen/blob/master/.github/workflows/ci.yml"
    click storybook_cfg "https://github.com/segmentio/evergreen/tree/master/.storybook/"
    click alert_pkg "https://github.com/segmentio/evergreen/tree/master/src/alert/"
    click buttons_pkg "https://github.com/segmentio/evergreen/tree/master/src/buttons/"
    click dialog_pkg "https://github.com/segmentio/evergreen/tree/master/src/dialog/"
    click ui_box_ser "https://github.com/segmentio/evergreen/blob/master/lib/testing/ui-box-snapshot-serializer.js"
    click theme_src "https://github.com/segmentio/evergreen/tree/master/src/theme/"
    click themes_default "https://github.com/segmentio/evergreen/tree/master/src/themes/default/"
    click themes_index "https://github.com/segmentio/evergreen/blob/master/src/themes/index.js"
    click hooks "https://github.com/segmentio/evergreen/tree/master/src/hooks/"
    click utils "https://github.com/segmentio/evergreen/tree/master/src/lib/"
    click icons_gen "https://github.com/segmentio/evergreen/tree/master/src/icons/generated/"
    click icon_src "https://github.com/segmentio/evergreen/blob/master/src/icons/src/Icon.js"
    click icon_wrapper "https://github.com/segmentio/evergreen/blob/master/src/icons/src/IconWrapper.js"
    click icons_index "https://github.com/segmentio/evergreen/blob/master/src/icons/index.js"
    click codemods "https://github.com/segmentio/evergreen/tree/master/codemods/"
    click sb_stories "https://github.com/segmentio/evergreen/tree/master/src/**/stories/"
    click next_docs "https://github.com/segmentio/evergreen/tree/master/docs/"
    click examples "https://github.com/segmentio/evergreen/tree/master/examples/ssr-next/"

    %% Styles
    classDef code fill:#ACE,stroke:#069
    classDef service fill:#CFC,stroke:#393
    classDef docs fill:#FCE,stroke:#E93
```
