# golang/website architecture

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

- Interactive diagram: https://gitdiagram.com/golang/website
- Repository: https://github.com/golang/website

## Overview

##### Project Type and Purpose
- This is a monorepo for a full-stack web application: the Go project’s official content sites (go.dev, golang.org) plus the interactive Tour at go.dev/tour.
- Content (Markdown, templates, JS/TS/CSS) lives under `_content/` (site content) and `tour/` (tour content).
- Server binaries (Go programs) live in `cmd/`, supporting sites like `golangorg`, `adminapp`, `adminredirect`, plus the Tour server.
- Shared business logic and data handling is in `internal/` packages.

##### Main Components
A. Content Repositories
- `_content/`: Markdown, templates, static assets for go.dev and golang.org
- `tour/`: Go Tour content, static files, frontend app (Angular-like JS)
B. Build & Asset Pipeline
- Node/NPM tools (ESLint, Stylelint, Jest) enforce formatting & test JS/TS/CSS.
- TS builds: `.ts` files under `_content/ts` are compiled/transformed to JS at runtime or build time.
C. Backend Servers (Go)
- cmd/golangorg: main combined go.dev + golang.org server
- cmd/googlegolangorg & cmd/adminapp & cmd/adminredirect: auxiliary admin and regional servers
- tour/main.go: Go Tour server
D. Internal Libraries (`internal/`)
- `internal/web`: page routing, rendering, template functions
- `internal/gitfs`: overlays Git content onto a virtual FS
- `internal/blog`, `internal/talks`, `internal/pkgdoc`, `internal/tour`: domain logic for each section
- `internal/memcache`: caching layer
- `internal/api`: JSON API endpoints
- `internal/redirect`, `internal/short`: URL rewriting/short URLs
E. External Services
- Google App Engine (hosting)
- Cloud Build (CI/CD)
- Google Cloud Storage or memcache for caching static data
- Gerrit (code review)

##### Relationships & Interactions
- Content authors update Markdown/Tmpl in `_content/` or `tour/`.
- On `go run ./cmd/golangorg`, the server:
- Uses `internal/gitfs` to load content directly from the Git checkout
- Passes content through `internal/texthtml` & `internal/tmplfunc` to generate HTML
- Uses `internal/web` to route requests and render pages
- Serves static assets (CSS/JS/images) from `_content` subdirectories via HTTP handlers
- Executes TS transforms on the fly or via a prebuild step
- Admin servers use the same `internal` libraries but different content roots.
- The Tour server serves a SPA: static HTML + JS frontend (in `tour/static`) communicating with `internal/tour` API backends.

##### Architectural Patterns & Design Principles
- Modular monolith: multiple Go “commands” sharing `internal/` libraries
- Clear separation of concerns:
- Content storage (Markdown, static assets)
- Content rendering pipeline (`texthtml`, `tmplfunc`)
- HTTP routing & server logic (`web`)
- Cache-aside pattern: `internal/memcache` caches rendered pages or data
- Virtual file system (GitFS) abstracts underlying storage from rendering code
- CI/CD via Cloud Build automatically deploys each command to App Engine

##### Key Elements to Label
- Asset pipeline: `npx eslint`, `npx stylelint`, `npx jest`, TS compiler
- Go commands: `cmd/golangorg`, `cmd/adminapp`, `cmd/tour`
- Shared libs: `internal/web`, `internal/gitfs`, `internal/pkgdoc`, `internal/memcache`, etc.
- External: Google App Engine, Cloud Build, Gerrit

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    subgraph "Content Layer"
        CContent["_content/"]:::content
        CTour["tour/"]:::content
    end

    %% Asset Pipeline Layer
    subgraph "Asset Pipeline"
        PackageJSON["package.json"]:::pipeline
        TSConfig["tsconfig.json"]:::pipeline
        ESLintConfig[".eslintrc.yaml"]:::pipeline
        StylelintConfig[".stylelintrc.yaml"]:::pipeline
        ESLint["npx eslint"]:::pipeline
        Stylelint["npx stylelint"]:::pipeline
        Jest["npx jest"]:::pipeline
        TSCompiler["TS Compiler"]:::pipeline
        StaticAssets["Optimized Static Assets"]:::pipeline
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        Web["internal/web/"]:::lib
        GitFS["internal/gitfs/"]:::lib
        Blog["internal/blog/"]:::lib
        PkgDoc["internal/pkgdoc/"]:::lib
        TourLib["internal/tour/"]:::lib
        TextHTML["internal/texthtml/"]:::lib
        TmplFunc["internal/tmplfunc/"]:::lib
        RedirectShort["internal/redirect/ & internal/short/"]:::lib
        Memcache["internal/memcache/"]:::lib
        API["internal/api/"]:::lib
        CmdTools["cmd/locktrigger/, screentest/, versionprune/"]:::lib
    end

    %% Go Server Layer
    subgraph "Go Server Layer"
        GolangOrg["cmd/golangorg"]:::server
        AdminApp["cmd/adminapp"]:::server
        AdminRedirect["cmd/adminredirect"]:::server
        ChinaServer["cmd/googlegolangorg"]:::server
        TourServer["tour/main.go"]:::server
    end

    %% External Services
    subgraph "External Services"
        AppEngine["Google App Engine"]:::external
        CloudBuild["Cloud Build"]:::external
        Gerrit["Gerrit"]:::external
        CacheService["Cloud Storage / External Cache"]:::external
    end

    %% Data Flows
    CContent -->|provides content| ESLint
    CContent -->|provides content| Stylelint
    CContent -->|provides content| Jest
    CContent -->|provides content| TSCompiler

    CTour -->|provides content| ESLint
    CTour -->|provides content| Stylelint
    CTour -->|provides content| Jest
    CTour -->|provides content| TSCompiler

    PackageJSON --> ESLint
    PackageJSON --> Stylelint
    PackageJSON --> Jest
    TSConfig --> TSCompiler
    ESLintConfig --> ESLint
    StylelintConfig --> Stylelint

    ESLint --> StaticAssets
    Stylelint --> StaticAssets
    Jest --> StaticAssets
    TSCompiler --> StaticAssets

    CContent -->|serves via| GitFS
    CTour -->|serves via| GitFS

    GitFS --> Web
    TextHTML --> Web
    TmplFunc --> Web

    Web --> GolangOrg
    Web --> AdminApp
    Web --> AdminRedirect
    Web --> ChinaServer
    Web --> TourServer

    StaticAssets --> GolangOrg
    StaticAssets --> AdminApp
    StaticAssets --> AdminRedirect
    StaticAssets --> ChinaServer
    StaticAssets --> TourServer

    Blog --> GolangOrg
    Blog --> AdminApp
    PkgDoc --> GolangOrg
    TourLib --> TourServer
    API --> TourServer
    RedirectShort --> GolangOrg
    Memcache --> GolangOrg
    Memcache --> AdminApp
    Memcache --> AdminRedirect
    Memcache --> ChinaServer
    Memcache --> TourServer
    CmdTools --> GolangOrg

    %% CI/CD Pipeline
    Gerrit --> CloudBuild
    CloudBuild -->|builds binaries| GolangOrg
    CloudBuild -->|builds binaries| AdminApp
    CloudBuild -->|builds binaries| AdminRedirect
    CloudBuild -->|builds binaries| ChinaServer
    CloudBuild -->|builds binaries| TourServer
    GolangOrg -->|deployed to| AppEngine
    AdminApp -->|deployed to| AppEngine
    AdminRedirect -->|deployed to| AppEngine
    ChinaServer -->|deployed to| AppEngine
    TourServer -->|deployed to| AppEngine

    GolangOrg -->|uses| CacheService
    AdminApp -->|uses| CacheService
    AdminRedirect -->|uses| CacheService
    ChinaServer -->|uses| CacheService
    TourServer -->|uses| CacheService

    %% Click Events
    click CContent "https://github.com/golang/website/tree/master/_content/"
    click CTour "https://github.com/golang/website/tree/master/tour/"
    click PackageJSON "https://github.com/golang/website/blob/master/package.json"
    click TSConfig "https://github.com/golang/website/blob/master/tsconfig.json"
    click ESLintConfig "https://github.com/golang/website/blob/master/.eslintrc.yaml"
    click StylelintConfig "https://github.com/golang/website/blob/master/.stylelintrc.yaml"
    click GolangOrg "https://github.com/golang/website/tree/master/cmd/golangorg/"
    click AdminApp "https://github.com/golang/website/tree/master/cmd/adminapp/"
    click AdminRedirect "https://github.com/golang/website/tree/master/cmd/adminredirect/"
    click ChinaServer "https://github.com/golang/website/tree/master/cmd/googlegolangorg/"
    click TourServer "https://github.com/golang/website/blob/master/tour/main.go"
    click Web "https://github.com/golang/website/tree/master/internal/web/"
    click GitFS "https://github.com/golang/website/tree/master/internal/gitfs/"
    click Blog "https://github.com/golang/website/tree/master/internal/blog/"
    click PkgDoc "https://github.com/golang/website/tree/master/internal/pkgdoc/"
    click TourLib "https://github.com/golang/website/tree/master/internal/tour/"
    click TextHTML "https://github.com/golang/website/tree/master/internal/texthtml/"
    click TmplFunc "https://github.com/golang/website/tree/master/internal/tmplfunc/"
    click RedirectShort "https://github.com/golang/website/tree/master/internal/redirect/"
    click Memcache "https://github.com/golang/website/tree/master/internal/memcache/"
    click API "https://github.com/golang/website/tree/master/internal/api/"
    click CmdTools "https://github.com/golang/website/tree/master/cmd/locktrigger/"

    %% Styles
    classDef content fill:#a8e6cf,stroke:#333
    classDef pipeline fill:#d0e1f9,stroke:#333
    classDef server fill:#FFD8A9,stroke:#333
    classDef lib fill:#E0E0E0,stroke:#333
    classDef external fill:#D3C0EB,stroke:#333
```
