# googlecloudplatform/gcping architecture

> Architecture diagram of the GitHub repository googlecloudplatform/gcping, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/gcping
- Repository: https://github.com/googlecloudplatform/gcping

## Overview

GCPing is a latency-measurement product with a CLI, web application, browser extension, and regional HTTP services. Users obtain a region endpoint list, request regional pings, and compare latency results; the CLI also supports single-region, fastest-region, and CSV reports. The source shows the CLI, web, extension, and service-handler behavior. The README documents self-hosting through Terraform, but the deployment implementation was not sampled, so that relationship is marked unverified.

Main entry points: [`internal/httphandler/httphandler.go`](https://github.com/googlecloudplatform/gcping/blob/main/internal/httphandler/httphandler.go) (API and static handlers), [`main.go`](https://github.com/googlecloudplatform/gcping/blob/main/main.go) (CLI options), [`worker.go`](https://github.com/googlecloudplatform/gcping/blob/main/worker.go) (Ping workers), [`web/src/js/gcping.js`](https://github.com/googlecloudplatform/gcping/blob/main/web/src/js/gcping.js) (Web ping and results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Measurement clients"]
  node_cli["CLI options<br/>[main.go]"]
  node_cli_workers["Ping workers<br/>[worker.go]"]
  node_cli_report["CLI reports<br/>[worker.go]"]
  node_web_app["Web ping and results<br/>[gcping.js]"]
  node_extension["Extension ping<br/>[service-worker.js]"]
end

subgraph group_service["Regional service"]
  node_http_server["HTTP server<br/>[main.go]"]
  node_http_handlers["API and static handlers<br/>[httphandler.go]"]
end

subgraph group_config["Endpoint configuration"]
  node_endpoint_config["Region endpoints<br/>[endpoints.go]"]
end

subgraph group_deployment["Self-hosting"]
  node_deployment_config["Cloud Run deployment"]
end

node_user(("User"))
node_extension_user(("Extension user"))
node_regional_services["Regional ping services"]
node_web_static["Web assets<br/>[index.html]"]

node_user -->|"runs"| node_cli
node_cli -->|"fetches list"| node_endpoint_config
node_cli -->|"dispatches reports"| node_cli_workers
node_cli_workers -->|"requests pings"| node_regional_services
node_cli_workers -->|"collects timings"| node_cli_report
node_user -->|"opens app"| node_web_app
node_web_app -->|"fetches endpoints"| node_http_handlers
node_web_app -->|"measures latency"| node_regional_services
node_extension_user -->|"clicks action"| node_extension
node_extension -->|"requests pings"| node_regional_services
node_extension -->|"fetches list"| node_endpoint_config
node_http_server -->|"serves requests"| node_http_handlers
node_http_server -->|"provides endpoints"| node_endpoint_config
node_http_handlers -->|"serves files"| node_web_static
node_http_handlers -->|"returns region"| node_regional_services
node_deployment_config -.->|"deploys services"| node_http_server

click node_cli "https://github.com/googlecloudplatform/gcping/blob/main/main.go"
click node_cli_workers "https://github.com/googlecloudplatform/gcping/blob/main/worker.go"
click node_cli_report "https://github.com/googlecloudplatform/gcping/blob/main/worker.go"
click node_web_app "https://github.com/googlecloudplatform/gcping/blob/main/web/src/js/gcping.js"
click node_extension "https://github.com/googlecloudplatform/gcping/blob/main/ext/js/service-worker.js"
click node_endpoint_config "https://github.com/googlecloudplatform/gcping/blob/main/internal/config/endpoints.go"
click node_http_server "https://github.com/googlecloudplatform/gcping/blob/main/cmd/ping/main.go"
click node_http_handlers "https://github.com/googlecloudplatform/gcping/blob/main/internal/httphandler/httphandler.go"
click node_deployment_config "https://github.com/googlecloudplatform/gcping/tree/main/tools/terraform"
click node_web_static "https://github.com/googlecloudplatform/gcping/blob/main/web/src/index.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_workers,node_cli_report,node_web_app,node_extension,node_user,node_extension_user toneBlue
class node_http_server,node_http_handlers toneAmber
class node_endpoint_config toneMint
class node_deployment_config toneRose
class node_regional_services toneIndigo
class node_web_static toneTeal
```

## Components

### Measurement clients

- [CLI options](https://github.com/googlecloudplatform/gcping/blob/main/main.go): `main.go`
- [Ping workers](https://github.com/googlecloudplatform/gcping/blob/main/worker.go): `worker.go`
- [CLI reports](https://github.com/googlecloudplatform/gcping/blob/main/worker.go): `worker.go`
- [Web ping and results](https://github.com/googlecloudplatform/gcping/blob/main/web/src/js/gcping.js): `web/src/js/gcping.js`
- [Extension ping](https://github.com/googlecloudplatform/gcping/blob/main/ext/js/service-worker.js): `ext/js/service-worker.js`

### Regional service

- [HTTP server](https://github.com/googlecloudplatform/gcping/blob/main/cmd/ping/main.go): `cmd/ping/main.go`
- [API and static handlers](https://github.com/googlecloudplatform/gcping/blob/main/internal/httphandler/httphandler.go): `internal/httphandler/httphandler.go`

### Endpoint configuration

- [Region endpoints](https://github.com/googlecloudplatform/gcping/blob/main/internal/config/endpoints.go): `internal/config/endpoints.go`

### Self-hosting

- [Cloud Run deployment](https://github.com/googlecloudplatform/gcping/tree/main/tools/terraform): `tools/terraform`

### Other components

- **User**
- **Extension user**
- **Regional ping services**
- [Web assets](https://github.com/googlecloudplatform/gcping/blob/main/web/src/index.html): `web/src/index.html`

## Connections

- User → CLI options: runs (evidence: `README.md`)
- CLI options → Region endpoints: fetches list (evidence: `main.go`)
- CLI options → Ping workers: dispatches reports (evidence: `main.go`)
- Ping workers → Regional ping services: requests pings (evidence: `worker.go`)
- Ping workers → CLI reports: collects timings (evidence: `worker.go`)
- User → Web ping and results: opens app (evidence: `README.md`)
- Web ping and results → API and static handlers: fetches endpoints (evidence: `web/src/js/gcping.js`)
- Web ping and results → Regional ping services: measures latency (evidence: `web/src/js/gcping.js`)
- Extension user → Extension ping: clicks action (evidence: `ext/js/service-worker.js`)
- Extension ping → Regional ping services: requests pings (evidence: `ext/js/service-worker.js`)
- Extension ping → Region endpoints: fetches list (evidence: `ext/js/service-worker.js`)
- HTTP server → API and static handlers: serves requests (evidence: `cmd/ping/main.go`)
- HTTP server → Region endpoints: provides endpoints (evidence: `cmd/ping/main.go`)
- API and static handlers → Web assets: serves files (evidence: `internal/httphandler/httphandler.go`)
- API and static handlers → Regional ping services: returns region (evidence: `internal/httphandler/httphandler.go`)
- Cloud Run deployment → HTTP server: deploys services (evidence: `README.md`)
