# glasshouseventurestudio/glasshouse-stack architecture

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

- Interactive diagram: https://gitdiagram.com/glasshouseventurestudio/glasshouse-stack
- Repository: https://github.com/glasshouseventurestudio/glasshouse-stack

## Overview

##### Project Type and Purpose
- This is a frontend-focused monorepo (Turborepo) that hosts:
- A React component library (`@glasshouse/components`)
- Shared utilities (`@glasshouse/utils`)
- Shared style/config packages (`@glasshouse/style-guide`)
- A Storybook-powered docs site (`apps/docs`)
- (Optionally) a demo Next.js app (mentioned in README)
- It’s intended to be the single source of truth for Glasshouse UI building blocks, developer tools, and documentation, all orchestrated by Turborepo, Changesets, pnpm, and GitHub Actions.

##### Top-Level System Components
- Version Control & CI/CD Platform
- GitHub (main branch)
- GitHub Actions workflows (quality/lint, Chromatic, release)
- Changesets (semantic versioning & release orchestration)
- Monorepo Orchestrator
- Turborepo (task runner + caching)
- pnpm workspace (dependency manager)
- Packages (internal modules)
- style-guide: ESLint/Prettier/StyleLint/TS configs
- utils: shared React hooks & utilities
- components: UI primitives & patterns
- Applications
- docs: Storybook site that:
– Imports components + utils + style-guide configs
– Serves documentation & visual regression (Chromatic)
- (demo): Next.js demo site that imports published packages
- External Services
- npm registry (public publishing)
- GitHub Packages (optional)
- Chromatic (storybook visual tests)

##### Relationships & Data Flows
- Developer commits → GitHub → triggers CI pipelines
- “changeset” CLI → generates version bump PR → merge → GitHub Actions release → publishes to npm
- Turborepo coordinates build/test/lint across packages & apps
- docs site depends on local packages (via pnpm workspace links) during dev, and on published packages in CI for Chromatic
- apps/docs → Storybook → Chromatic
- apps/demo (Next.js) → imports published packages from npm / GitHub Packages

##### Architectural Patterns & Design Principles
- Monorepo with clear package boundaries
- Task orchestration & remote cache (Turborepo)
- Semantic versioning via Changesets
- CI pipeline per concern: lint/test/build, visual test, release
- Code sharing via workspaces (pnpm) and peer dependencies
- Documentation as first-class citizen (Storybook)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Infrastructure
    subgraph "Infrastructure"
        GitHub[/GitHub/]:::infra
        subgraph "CI/CD Pipelines"
            Quality["Quality/Lint/Test"]:::ci
            ChromaticCI["Chromatic Visual Tests"]:::ci
            Release["Release"]:::ci
            Composite["Composite Actions"]:::ci
        end
        Changesets["Changesets"]:::ci
    end

    %% Monorepo Root
    subgraph "Monorepo Root"
        Turbo["Turborepo"]:::orchestrator
        PNPM["pnpm Workspace"]:::orchestrator
    end

    %% Packages
    subgraph "Internal Packages"
        StyleGuide["@glasshouse/style-guide"]:::pkg
        Utils["@glasshouse/utils"]:::pkg
        Components["@glasshouse/components"]:::pkg
    end

    %% Applications
    subgraph "Applications"
        Docs["docs (Storybook)"]:::app
        Demo["demo (Next.js)"]:::app
    end

    %% External Services
    subgraph "External Services"
        npm[(npm Registry)]:::ext
        GH_Packages[(GitHub Packages)]:::ext
        ChromaticExt[(Chromatic)]:::ext
    end

    %% Relationships
    GitHub -->|"git push"| Quality
    GitHub -->|"git push"| ChromaticCI
    GitHub -->|"git push"| Release

    Quality -->|runs| Turbo
    Quality -->|runs| PNPM

    Turbo -->|build/test/lint| StyleGuide
    Turbo -->|build/test/lint| Utils
    Turbo -->|build/test/lint| Components
    Turbo -->|build/test/lint| Docs
    Turbo -->|build/test/lint| Demo

    PNPM -->|workspace links| StyleGuide
    PNPM -->|workspace links| Utils
    PNPM -->|workspace links| Components

    StyleGuide -->|inherits configs| Utils
    StyleGuide -->|inherits configs| Components
    StyleGuide -->|inherits configs| Docs
    StyleGuide -->|inherits configs| Demo

    Utils -->|provides hooks/utilities| Components
    Components -->|UI primitives| Docs
    Components -->|UI primitives| Demo

    Docs -->|Storybook| ChromaticExt
    Docs -->|imports local| StyleGuide
    Docs -->|imports local| Utils
    Docs -->|imports local| Components

    Release -->|publishes via Changesets| npm
    Changesets -->|triggers| Release

    Demo -->|imports published| npm
    Demo -->|imports published| GH_Packages

    %% Click Events
    click GitHub "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/.gitignore"
    click Quality "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/.github/workflows/quality.yml"
    click ChromaticCI "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/.github/workflows/chromatic.yml"
    click Release "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/.github/workflows/release.yml"
    click Composite "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/.github/composite-actions/install/action.yml"
    click Changesets "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/.changeset/config.json"
    click Turbo "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/turbo.json"
    click PNPM "https://github.com/glasshouseventurestudio/glasshouse-stack/blob/main/pnpm-workspace.yaml"
    click StyleGuide "https://github.com/glasshouseventurestudio/glasshouse-stack/tree/main/packages/style-guide"
    click Utils "https://github.com/glasshouseventurestudio/glasshouse-stack/tree/main/packages/utils"
    click Components "https://github.com/glasshouseventurestudio/glasshouse-stack/tree/main/packages/components"
    click Docs "https://github.com/glasshouseventurestudio/glasshouse-stack/tree/main/apps/docs"

    %% Styles
    classDef infra fill:#ffd27f,stroke:#bb8000,stroke-width:1px
    classDef ci fill:#ffb085,stroke:#aa5500,stroke-width:1px
    classDef orchestrator fill:#ffcc99,stroke:#bb8844,stroke-width:1px
    classDef pkg fill:#9fd3ff,stroke:#0066cc,stroke-width:1px
    classDef app fill:#a2ffa3,stroke:#228822,stroke-width:1px
    classDef ext fill:#dddddd,stroke:#888888,stroke-width:1px
```
