# justeattakeaway/pie architecture

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

- Interactive diagram: https://gitdiagram.com/justeattakeaway/pie
- Repository: https://github.com/justeattakeaway/pie

## Overview

##### Project Type & Purpose
- A monorepo (managed by Yarn Workspaces & Turborepo) hosting PIE, Just Eat Takeaway’s global design system.
- It comprises three main sections:
– pie-docs: a static documentation site built with Eleventy.
– pie-storybook: a Storybook playground (MDX/TS) for Web Components.
– packages:
- components: dozens of Web Component packages (TS + Vite builds + custom-elements-manifest).
- CI/CD via GitHub Actions, publishing via Changesets to npm, hosting docs/storybook on AWS Amplify/CDN.

##### File-Structure Analysis
- Root:
– package.json, tsconfig.json, turbo.json, yarnrc.yml
– .configs & .github/workflows
- apps/
– pie-docs/ → Eleventy + Vite + Playwright/Visual Tests + static assets
– pie-storybook/ → Storybook configs + MDX stories + test utilities
- packages/
– components/ → one folder per component, each with src/, tests (accessibility/visual/unit), package.json, Vite configs
- configs/ → shared Vite/Changesets/Playwright setups for components

##### README Insights
- Confirms monorepo’s three pillars: docs, storybook, web components.
- References contributing guide, workflow tooling (DangerJS, Changesets, OSSF Scorecard).

##### Diagramming the Architecture
a. Main Components
1. Developer Workstation
2. GitHub Repo + GitHub Actions (CI/CD)
3. Monorepo Orchestration: Yarn Workspaces + Turborepo pipeline
4. Apps:
– pie-docs (Eleventy → static HTML/CSS/JS)
– pie-storybook (Storybook → static build)
5. Packages:
– components (Web Components + TS + Vite → distributed to npm & CDN)
– tools (lint configs, generators, CSS utilities)
6. External Services:
– npm Registry
– AWS Amplify / S3 / CloudFront (pie.design, webc.pie.design)
– Playwright & Percy (E2E & visual regression)
– Changesets (versioning + releases)

b. Relationships & Interactions
- Developer → pushes PR → GitHub Actions
- CI: Turborepo runs tasks in parallel (build, test, lint) across apps & packages
- On release: Changesets publishes updated packages to npm + deploys static sites to Amplify
- Apps consume Web Components via published packages (docs auto-import component JSON manifests & CSS)
- Storybook loads all components for interactive playground & MDX docs

c. Architectural Patterns & Principles
- Monorepo with workspace boundaries; Turborepo for build caching & orchestration
- Component-based architecture: each UI widget is a standalone package
- Static-first Frontend: Eleventy and Storybook produce static assets
- Polyglot tooling: shared config in /configs & /packages/tools

d. Key Technologies & Frameworks
- Yarn 3 Workspaces, Turborepo
- TypeScript, Vite, Rollup (for React wrappers), custom-elements-manifest
- Eleventy (pie-docs), Storybook (pie-storybook)
- Playwright, Percy for testing
- Changesets, DangerJS for releases
- AWS Amplify / S3 / CloudFront, npm Registry

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Environment"
        Dev["Developer Workstation"]:::actor
    end

    Dev -->|push PR| GitHub["GitHub Repo"]:::ci
    GitHub -->|trigger| GA["GitHub Actions"]:::ci
    GA -->|uses| SetupActions["CI Setup Actions"]:::ci

    subgraph "Monorepo Core"
        Root["Monorepo Orchestration\n(Yarn Workspaces & Turborepo)"]:::core
        SharedConfigs["Shared Configs"]:::config
    end

    GA -->|runs| Root
    Root -->|loads| SharedConfigs

    subgraph Apps
        Docs["pie-docs\n(Eleventy)"]:::app
        Storybook["pie-storybook\n(Storybook)"]:::app
    end

    Root -->|build/test| Docs
    Root -->|build/test| Storybook

    subgraph Packages
        Components["Web Component Packages"]:::package
        ESLint["eslint-config-pie"]:::tool
        Stylelint["stylelint-config-pie"]:::tool
        CSSBuilder["pie-css"]:::tool
        Icons["pie-icons"]:::tool
        Utils["pie-monorepo-utils"]:::tool
    end

    Root -->|orchestrates| Components
    Root -->|orchestrates| ESLint
    Root -->|orchestrates| Stylelint
    Root -->|orchestrates| CSSBuilder
    Root -->|orchestrates| Icons
    Root -->|orchestrates| Utils

    Components -->|src→build→tests| Docs
    Components -->|src→build→tests| Storybook

    GA -->|run tests| PlaywrightPercy["Playwright & Percy"]:::external

    GA -->|release| ChangesetsService["Changesets"]:::external
    ChangesetsService -->|publish| NPM["npm Registry"]:::external
    ChangesetsService -->|deploy| Amplify["AWS Amplify / CDN"]:::external

    Docs -->|host| Amplify
    Storybook -->|host| Amplify

    classDef actor fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef ci fill:#fff3e0,stroke:#e65100,color:#bf360c;
    classDef core fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef config fill:#f1f8e9,stroke:#558b2f,color:#33691e;
    classDef app fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
    classDef package fill:#fff8e1,stroke:#f9a825,color:#ff6f00;
    classDef tool fill:#fffde7,stroke:#fbc02d,color:#f57f17;
    classDef external fill:#eceff1,stroke:#546e7a,color:#37474f;

    click Root "https://github.com/justeattakeaway/pie/blob/main//package.json"
    click Root "https://github.com/justeattakeaway/pie/blob/main//turbo.json"
    click Root "https://github.com/justeattakeaway/pie/blob/main//yarnrc.yml"
    click GA "https://github.com/justeattakeaway/pie/tree/main//.github/workflows"
    click SetupActions "https://github.com/justeattakeaway/pie/tree/main//.github/actions"
    click SharedConfigs "https://github.com/justeattakeaway/pie/tree/main//configs"
    click Docs "https://github.com/justeattakeaway/pie/tree/main//apps/pie-docs"
    click Storybook "https://github.com/justeattakeaway/pie/tree/main//apps/pie-storybook"
    click Components "https://github.com/justeattakeaway/pie/tree/main//packages/components"
    click ESLint "https://github.com/justeattakeaway/pie/tree/main//packages/tools/eslint-config-pie"
    click Stylelint "https://github.com/justeattakeaway/pie/tree/main//packages/tools/stylelint-config-pie"
    click CSSBuilder "https://github.com/justeattakeaway/pie/tree/main//packages/tools/pie-css"
    click Icons "https://github.com/justeattakeaway/pie/tree/main//packages/tools/pie-icons"
    click Utils "https://github.com/justeattakeaway/pie/tree/main//packages/tools/pie-monorepo-utils"
    click ChangesetsService "https://github.com/justeattakeaway/pie/blob/main//.changeset"
```
