# googlecodelabs/codelab-elements architecture

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

- Interactive diagram: https://gitdiagram.com/googlecodelabs/codelab-elements
- Repository: https://github.com/googlecodelabs/codelab-elements

## Overview

##### Project Type and Purpose
- This is an open-source web-component library (“Codelab Custom Elements”) that provides reusable Custom Elements (analytics, index, core codelab, steps, survey) for building interactive codelabs.
- It is organized as a Bazel-based monorepo, with each element in its own package, plus a demo, third-party shims, and development tools.

##### File Structure Analysis
- Top-level
- BUILD.bazel, WORKSPACE – Bazel workspace definition and build rules.
- demo/ – example application showing how to use the components; contains its own BUILD.bazel, HTML, JS, tests, and images.
- google-codelab-analytics/, google-codelab-index/, google-codelab-step/, google-codelab-survey/, google-codelab/ – five independent component packages, each with a BUILD.bazel, HTML/CSS/JS sources, definitions, tests, and assets.
- third_party/ – Bazel build rules for polyfills and shims (ES6, polyfill, prettify).
- tools/ – CI scripts, Bazel config, server.go and webtest.go for local dev server and browser tests.
- Patterns
- Modular packages built via Bazel, using Google Closure Compiler for JS bundling and testing.
- Test targets in each package.
- A dev web server to serve built artifacts for manual inspection.

##### README Insights
- Describes standard Custom Elements usage.
- “bazel build :bundle” emits codelab-elements.js, codelab-elements.css for direct inclusion in HTML.
- Demo uses native-shim, custom-elements polyfill, prettify, then the bundled JS/CSS.
- Emphasis on no framework dependencies, only standards-based web components.

1. Monorepo Source Packages
– google-codelab (core renderer/navigator)
– google-codelab-step (step component)
– google-codelab-index (index/cards component)
– google-codelab-analytics (analytics wrapper)
– google-codelab-survey (survey component)
2. Third-Party Shims/Polyfills (ES6, Custom Elements polyfill, prettify)
3. Build System
– Bazel (WORKSPACE, BUILD.bazel rules)
– Google Closure Compiler & Library
– Bundling target (:bundle) producing JS and CSS artifacts
4. Demo Application
– HTML pages (codelab embed, hello, codelab-index)
– hello.js test driver and test suite
– bazel run tools:server (dev web server)
5. CI/Testing Tools
– tools/ci-presubmit.sh, ci-continuous.sh
– Webtest and Go server for browser-based tests
6. Runtime Environment (Browser)
– Native browser HTML/CSS/JS
– Custom Elements lifecycle
– User interactions driving codelab steps and events forwarded to analytics and survey components

- Each source package → Bazel compiler → bundle artifacts.
- third_party shims → bundled with component outputs.
- Demo HTML → includes bundle artifacts + polyfills → browser runtime.
- User clicks “Next Step” → google-codelab triggers google-codelab-step → updates DOM → optional survey popup → events → google-codelab-analytics.
- CI scripts → run bazel test on each package → report results.

c. Architectural Patterns & Principles
- Modular, packaging each component separately (Single Responsibility).
- Build pipeline orchestrated by Bazel (hermetic, reproducible).
- Standards-based Custom Elements (no framework lock-in).
- Test pyramid: unit tests per component + integration via demo + browser tests.

d. Key Technologies
- Bazel (build, test, run)
- Google Closure Compiler & Library
- JavaScript Custom Elements API
- SCSS → CSS for styling
- Go (tools/server.go for local web server)
- HTML for demos and component templates

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Source Packages
  subgraph "Source Packages"
    direction TB
    Core["google-codelab"]:::source
    Step["google-codelab-step"]:::source
    Index["google-codelab-index"]:::source
    Analytics["google-codelab-analytics"]:::source
    Survey["google-codelab-survey"]:::source
  end

  %% Third-Party
  subgraph "Third-Party Shims/Polyfills"
    direction TB
    ES6["ES6 Shim"]:::third
    Polyfill["Custom Elements Polyfill"]:::third
    Prettify["Prettify"]:::third
  end

  %% Build System
  subgraph "Build & Bundling" 
    direction TB
    BazelWorkspace["WORKSPACE & BUILD.bazel"]:::build
    Closure["Google Closure Compiler"]:::build
    Bundle["//:bundle → codelab-elements.js/css"]:::build
  end

  %% Demo Application
  subgraph "Demo Application"
    direction TB
    CodelabHTML["codelab.html/embed.html/hello.html"]:::demo
    HelloJS["hello.js & hello_test.js"]:::demo
    DemoImg["img/"]:::demo
  end

  %% CI/Test & Dev Server
  subgraph "CI & Dev Server"
    direction TB
    CIPresubmit["ci-presubmit.sh"]:::build
    CIContinuous["ci-continuous.sh"]:::build
    ServerGo["server.go"]:::build
    WebtestGo["webtest.go"]:::build
  end

  %% Runtime
  subgraph "Browser Runtime"
    direction TB
    Browser["Browser (HTML/CSS/JS)"]:::runtime
  end

  %% Build Flow
  Core -->|sources| BazelWorkspace
  Step -->|sources| BazelWorkspace
  Index -->|sources| BazelWorkspace
  Analytics -->|sources| BazelWorkspace
  Survey -->|sources| BazelWorkspace
  BazelWorkspace --> Closure
  Closure --> Bundle
  ES6 --> Bundle
  Polyfill --> Bundle
  Prettify --> Bundle

  %% Demo & Runtime Flow
  Bundle --> CodelabHTML
  CodelabHTML --> Browser
  ES6 --> Browser
  Polyfill --> Browser
  Prettify --> Browser

  %% User Interaction Flow
  Browser -->|"User clicks Next"| Core
  Core -->|"triggers step"| Step
  Step -->|"updates DOM"| Browser
  Browser -->|"survey popup"| Survey
  Survey -->|"event sent"| Analytics

  %% CI/Test Flow
  CIPresubmit -->|runs| BazelWorkspace
  CIContinuous -->|runs| BazelWorkspace
  BazelWorkspace -->|test| Core
  BazelWorkspace -->|test| Step
  BazelWorkspace -->|test| Index
  BazelWorkspace -->|test| Analytics
  BazelWorkspace -->|test| Survey
  WebtestGo -->|browser tests| Browser
  ServerGo -->|serves artifacts| Browser

  %% Click Events for component mapping
  click Core "https://github.com/googlecodelabs/codelab-elements/tree/master/google-codelab/"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/BUILD.bazel"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/google_codelab.js"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/google_codelab_def.js"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/google_codelab.scss"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/_drawer.scss"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/_steps.scss"
  click Core "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab/index.html"
  click Core "https://github.com/googlecodelabs/codelab-elements/tree/master/google-codelab/img/"
  click Step "https://github.com/googlecodelabs/codelab-elements/tree/master/google-codelab-step/"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/BUILD.bazel"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/google_codelab_step.js"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/google_codelab_step_def.js"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/google_codelab_step.scss"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/google-codelab-step.html"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/_syntax.scss"
  click Step "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-step/google_codelab_step_test.js"
  click Index "https://github.com/googlecodelabs/codelab-elements/tree/master/google-codelab-index/"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/BUILD.bazel"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/google_codelab_index.js"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/google_codelab_index_def.js"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/google_codelab_index_cards.js"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/google_codelab_index_cards_def.js"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/google_codelab_index.scss"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/_cards.scss"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/_categories.scss"
  click Index "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-index/index.html"
  click Analytics "https://github.com/googlecodelabs/codelab-elements/tree/master/google-codelab-analytics/"
  click Analytics "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-analytics/BUILD.bazel"
  click Analytics "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-analytics/google_codelab_analytics.js"
  click Analytics "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-analytics/google_codelab_analytics_def.js"
  click Analytics "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-analytics/google_codelab_analytics_test.js"
  click Survey "https://github.com/googlecodelabs/codelab-elements/tree/master/google-codelab-survey/"
  click Survey "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-survey/BUILD.bazel"
  click Survey "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-survey/google_codelab_survey.js"
  click Survey "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-survey/google_codelab_survey_def.js"
  click Survey "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-survey/google_codelab_survey.scss"
  click Survey "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-survey/google-codelab-survey.html"
  click Survey "https://github.com/googlecodelabs/codelab-elements/blob/master/google-codelab-survey/google_codelab_survey_test.js"
  click CodelabHTML "https://github.com/googlecodelabs/codelab-elements/blob/master/demo/codelab.html"
  click CodelabHTML "https://github.com/googlecodelabs/codelab-elements/blob/master/demo/embed.html"
  click CodelabHTML "https://github.com/googlecodelabs/codelab-elements/blob/master/demo/hello.html"
  click HelloJS "https://github.com/googlecodelabs/codelab-elements/blob/master/demo/hello.js"
  click HelloJS "https://github.com/googlecodelabs/codelab-elements/blob/master/demo/hello_test.js"
  click DemoImg "https://github.com/googlecodelabs/codelab-elements/tree/master/demo/img/"
  click ES6 "https://github.com/googlecodelabs/codelab-elements/blob/master/third_party/BUILD.es6shim"
  click Polyfill "https://github.com/googlecodelabs/codelab-elements/blob/master/third_party/BUILD.polyfill"
  click Prettify "https://github.com/googlecodelabs/codelab-elements/blob/master/third_party/BUILD.prettify"
  click BazelWorkspace "https://github.com/googlecodelabs/codelab-elements/tree/master/WORKSPACE"
  click BazelWorkspace "https://github.com/googlecodelabs/codelab-elements/blob/master/BUILD.bazel"
  click CIPresubmit "https://github.com/googlecodelabs/codelab-elements/blob/master/tools/ci-presubmit.sh"
  click CIContinuous "https://github.com/googlecodelabs/codelab-elements/blob/master/tools/ci-continuous.sh"
  click ServerGo "https://github.com/googlecodelabs/codelab-elements/blob/master/tools/server.go"
  click WebtestGo "https://github.com/googlecodelabs/codelab-elements/blob/master/tools/webtest.go"

  %% Styles
  classDef source fill:#9f6,stroke:#090,color:#000
  classDef build fill:#6cf,stroke:#039,color:#000
  classDef demo fill:#6cf,stroke:#036,color:#fff
  classDef third fill:#ccc,stroke:#888,color:#000
  classDef runtime fill:#fc6,stroke:#f80,color:#000
```
