# badges/shields architecture

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

- Interactive diagram: https://gitdiagram.com/badges/shields
- Repository: https://github.com/badges/shields

## Overview

#### Purpose and entry points
Shields.io is a Node.js service that produces SVG and raster status badges from static parameters or live third-party data. It also ships the standalone `badge-maker` npm library and a Docusaurus documentation/frontend site. Runtime server entry points are `server.js` and `core/server/server.js`; local startup also runs the frontend in `frontend/`.

#### HTTP server and request lifecycle
The server accepts badge URLs, serves error/static pages, applies logging and exposes operational metrics. It resolves routes to badge services, handles failures, and returns rendered badge responses with cache semantics.
- `server.js`
- `core/server/server.js`
- `core/server/log.js`
- `core/server/error-pages/`

#### Service discovery and routing
Badge definitions are modular service classes/files, loaded and validated into route definitions. URL construction/parsing and route matching bridge external HTTP paths to a selected service handler. Service categories and the aggregate registry support discovery by the frontend and API consumers.
- `core/base-service/loader.js`
- `core/base-service/route.js`
- `core/base-service/service-definitions.js`
- `services/index.js`
- `services/route-builder.js`

#### Service execution boundary
Services encapsulate integrations with external APIs, registries, CI systems, and websites. They inherit shared base classes for HTTP, JSON, XML, YAML, TOML, JSONL, GraphQL, static, or SVG-scraping sources; these centralize request policy, validation, authentication, error mapping, tracing, caching/coalescing, and redirect behavior. Representative service families include GitHub, npm, GitLab, and generic dynamic/endpoint badges.
- `core/base-service/base.js`
- `core/base-service/base-json.js`
- `core/base-service/base-graphql.js`
- `core/base-service/got.js`
- `services/github/github-api-provider.js`
- `services/npm/npm-base.js`
- `services/dynamic/dynamic-json.service.js`

#### Badge construction and rendering
A handler produces normalized badge data (label, message, colors, links, logo/style options); the rendering layer turns it into SVG and related formats. The public npm library exposes the same badge-generation capability independently of the hosted service. Badge URL utilities support static/custom badge forms.
- `badge-maker/lib/index.js`
- `badge-maker/lib/make-badge.js`
- `badge-maker/lib/badge-renderers.js`
- `core/badge-urls/make-badge-url.js`
- `services/static-badge/static-badge.service.js`

#### State, credentials, and rate limits
Configuration is environment-specific. External credentials are handled through service authentication helpers and provider-specific logic. Token pooling persists and allocates tokens through SQL-backed persistence, protecting quota-constrained integrations such as GitHub. Response/resource caches and request coalescing reduce duplicated upstream work.
- `config/default.yml`
- `config/custom-environment-variables.yml`
- `core/base-service/auth-helper.js`
- `core/token-pooling/token-pool.js`
- `core/token-pooling/sql-token-persistence.js`
- `migrations/1676731511125_initialize.cjs`

#### Observability and deployment
The Node 24 service is containerized and can run via Docker or a Procfile-oriented host; Fly configuration is present. Metrics can be exported to Prometheus or InfluxDB, with Sentry configured externally through runtime configuration. GitHub Actions builds, validates, releases, and deploys docs/review environments.
- `Dockerfile`
- `Procfile`
- `fly.toml`
- `core/server/prometheus-metrics.js`
- `core/server/influx-metrics.js`

#### Documentation frontend
A separate Docusaurus application provides badge discovery, URL composition, documentation, and community pages. It consumes the service’s badge definitions/API-facing route metadata rather than implementing upstream integrations itself.
- `frontend/docusaurus.config.cjs`
- `frontend/src/pages/index.js`
- `frontend/src/theme/ApiDemoPanel/`
- `frontend/docs/static-badges.md`

Main entry points: [`core/server/server.js`](https://github.com/badges/shields/blob/master/core/server/server.js) (HTTP lifecycle), [`services/index.js`](https://github.com/badges/shields/blob/master/services/index.js) (Service registry), [`services/github/github-api-provider.js`](https://github.com/badges/shields/blob/master/services/github/github-api-provider.js) (Badge service handlers), [`core/base-service/base.js`](https://github.com/badges/shields/blob/master/core/base-service/base.js) (Shared service base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Hosted badge service"]
  node_server_entry["Server entry point<br/>Node bootstrap<br/>[server.js]"]
  node_http_server["HTTP lifecycle<br/>HTTP server<br/>[server.js]"]
  node_logging["Request logging<br/>[log.js]"]
  node_error_pages["Error and static pages<br/>HTTP pages"]
end

subgraph group_services["Service platform"]
  node_service_loader["Service loader<br/>discovery<br/>[loader.js]"]
  node_route_matching["Route parsing and matching<br/>routing<br/>[route.js]"]
  node_service_registry["Service registry<br/>service catalog<br/>[index.js]"]
  node_service_handlers["Badge service handlers<br/>service integrations"]
  node_service_base["Shared service base<br/>integration runtime<br/>[base.js]"]
end

subgraph group_rendering["Badge generation"]
  node_badge_url["Badge URL builder<br/>URL utility<br/>[make-badge-url.js]"]
  node_badge_renderer["Badge renderer<br/>SVG/raster rendering<br/>[badge-renderers.js]"]
  node_badge_maker["badge-maker library<br/>npm library<br/>[index.js]"]
end

subgraph group_state["State and operations"]
  node_auth["Auth helpers<br/>credentials<br/>[auth-helper.js]"]
  node_token_pool["Token pool<br/>quota management<br/>[token-pool.js]"]
  node_token_store[("SQL token persistence<br/>SQL persistence")]
  node_metrics["Metrics exporters<br/>observability"]
  node_runtime_config["Runtime configuration<br/>environment config<br/>[default.yml]"]
  node_deployment{{"Container deployment"}}
end

subgraph group_frontend["Documentation frontend"]
  node_docs_site["Docusaurus site<br/>documentation frontend"]
  node_api_demo["API demo panel<br/>frontend URL composer"]
end

node_server_entry -->|"starts"| node_http_server
node_http_server -->|"matches badge URL"| node_route_matching
node_http_server -->|"logs requests"| node_logging
node_http_server -->|"serves failures/pages"| node_error_pages
node_http_server -->|"reports operations"| node_metrics
node_route_matching -->|"selects definition"| node_service_registry
node_service_loader -->|"builds"| node_service_registry
node_service_registry -->|"registers"| node_service_handlers
node_service_handlers -->|"inherits execution policy"| node_service_base
node_service_base -->|"uses credentials"| node_auth
node_service_base -->|"acquires provider token"| node_token_pool
node_token_pool -->|"persists tokens"| node_token_store
node_service_handlers -->|"produces normalized badge"| node_badge_renderer
node_badge_renderer -->|"renders response"| node_http_server
node_badge_maker -->|"exposes rendering"| node_badge_renderer
node_badge_url -->|"creates compatible URLs"| node_route_matching
node_runtime_config -.->|"configures"| node_http_server
node_runtime_config -.->|"supplies credentials"| node_auth
node_deployment -->|"runs"| node_server_entry
node_docs_site -->|"consumes route metadata"| node_service_registry
node_api_demo -->|"composes badge URLs"| node_badge_url
node_docs_site -->|"hosts"| node_api_demo

click node_server_entry "https://github.com/badges/shields/blob/master/server.js"
click node_http_server "https://github.com/badges/shields/blob/master/core/server/server.js"
click node_logging "https://github.com/badges/shields/blob/master/core/server/log.js"
click node_service_loader "https://github.com/badges/shields/blob/master/core/base-service/loader.js"
click node_route_matching "https://github.com/badges/shields/blob/master/core/base-service/route.js"
click node_service_registry "https://github.com/badges/shields/blob/master/services/index.js"
click node_service_handlers "https://github.com/badges/shields/blob/master/services/github/github-api-provider.js"
click node_service_base "https://github.com/badges/shields/blob/master/core/base-service/base.js"
click node_auth "https://github.com/badges/shields/blob/master/core/base-service/auth-helper.js"
click node_token_pool "https://github.com/badges/shields/blob/master/core/token-pooling/token-pool.js"
click node_token_store "https://github.com/badges/shields/blob/master/core/token-pooling/sql-token-persistence.js"
click node_badge_url "https://github.com/badges/shields/blob/master/core/badge-urls/make-badge-url.js"
click node_badge_renderer "https://github.com/badges/shields/blob/master/badge-maker/lib/badge-renderers.js"
click node_badge_maker "https://github.com/badges/shields/blob/master/badge-maker/lib/index.js"
click node_metrics "https://github.com/badges/shields/blob/master/core/server/prometheus-metrics.js"
click node_runtime_config "https://github.com/badges/shields/blob/master/config/default.yml"
click node_deployment "https://github.com/badges/shields/blob/master/Dockerfile"
click node_docs_site "https://github.com/badges/shields/blob/master/frontend/docusaurus.config.cjs"

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_server_entry,node_http_server,node_logging,node_error_pages toneBlue
class node_service_loader,node_route_matching,node_service_registry,node_service_handlers,node_service_base toneAmber
class node_badge_url,node_badge_renderer,node_badge_maker toneMint
class node_auth,node_token_pool,node_token_store,node_metrics,node_runtime_config,node_deployment toneRose
class node_docs_site,node_api_demo toneIndigo
```

## Components

### Hosted badge service

- [Server entry point](https://github.com/badges/shields/blob/master/server.js): Node bootstrap · `server.js`
- [HTTP lifecycle](https://github.com/badges/shields/blob/master/core/server/server.js): HTTP server · Routes requests, serves errors, logs, and applies response caching. · `core/server/server.js`
- [Request logging](https://github.com/badges/shields/blob/master/core/server/log.js): logging · `core/server/log.js`
- **Error and static pages**: HTTP pages

### Service platform

- [Service loader](https://github.com/badges/shields/blob/master/core/base-service/loader.js): discovery · Loads and validates modular badge service definitions. · `core/base-service/loader.js`
- [Route parsing and matching](https://github.com/badges/shields/blob/master/core/base-service/route.js): routing · `core/base-service/route.js`
- [Service registry](https://github.com/badges/shields/blob/master/services/index.js): service catalog · Aggregates service categories for routing and consumers. · `services/index.js`
- [Badge service handlers](https://github.com/badges/shields/blob/master/services/github/github-api-provider.js): service integrations · GitHub, npm, GitLab, dynamic, endpoint, and other badge sources. · `services/github/github-api-provider.js`
- [Shared service base](https://github.com/badges/shields/blob/master/core/base-service/base.js): integration runtime · Centralizes upstream policy, validation, tracing, caching, redirects, and error mapping. · `core/base-service/base.js`

### Badge generation

- [Badge URL builder](https://github.com/badges/shields/blob/master/core/badge-urls/make-badge-url.js): URL utility · `core/badge-urls/make-badge-url.js`
- [Badge renderer](https://github.com/badges/shields/blob/master/badge-maker/lib/badge-renderers.js): SVG/raster rendering · Converts normalized badge data into SVG and related formats. · `badge-maker/lib/badge-renderers.js`
- [badge-maker library](https://github.com/badges/shields/blob/master/badge-maker/lib/index.js): npm library · Standalone public badge-generation API. · `badge-maker/lib/index.js`

### State and operations

- [Auth helpers](https://github.com/badges/shields/blob/master/core/base-service/auth-helper.js): credentials · `core/base-service/auth-helper.js`
- [Token pool](https://github.com/badges/shields/blob/master/core/token-pooling/token-pool.js): quota management · Allocates persisted provider tokens for quota-constrained APIs. · `core/token-pooling/token-pool.js`
- [SQL token persistence](https://github.com/badges/shields/blob/master/core/token-pooling/sql-token-persistence.js): SQL persistence · `core/token-pooling/sql-token-persistence.js`
- [Metrics exporters](https://github.com/badges/shields/blob/master/core/server/prometheus-metrics.js): observability · Exports operational metrics to Prometheus or InfluxDB. · `core/server/prometheus-metrics.js`
- [Runtime configuration](https://github.com/badges/shields/blob/master/config/default.yml): environment config · `config/default.yml`
- [Container deployment](https://github.com/badges/shields/blob/master/Dockerfile): deployment · Node 24 service deployment through Docker, Procfile hosts, or Fly. · `Dockerfile`

### Documentation frontend

- [Docusaurus site](https://github.com/badges/shields/blob/master/frontend/docusaurus.config.cjs): documentation frontend · Badge discovery, URL composition, docs, and community pages. · `frontend/docusaurus.config.cjs`
- **API demo panel**: frontend URL composer

## Connections

- Server entry point → HTTP lifecycle: starts
- HTTP lifecycle → Route parsing and matching: matches badge URL
- HTTP lifecycle → Request logging: logs requests
- HTTP lifecycle → Error and static pages: serves failures/pages
- HTTP lifecycle → Metrics exporters: reports operations
- Route parsing and matching → Service registry: selects definition
- Service loader → Service registry: builds
- Service registry → Badge service handlers: registers
- Badge service handlers → Shared service base: inherits execution policy
- Shared service base → Auth helpers: uses credentials
- Shared service base → Token pool: acquires provider token
- Token pool → SQL token persistence: persists tokens
- Badge service handlers → Badge renderer: produces normalized badge
- Badge renderer → HTTP lifecycle: renders response
- badge-maker library → Badge renderer: exposes rendering
- Badge URL builder → Route parsing and matching: creates compatible URLs
- Runtime configuration → HTTP lifecycle: configures
- Runtime configuration → Auth helpers: supplies credentials
- Container deployment → Server entry point: runs
- Docusaurus site → Service registry: consumes route metadata
- API demo panel → Badge URL builder: composes badge URLs
- Docusaurus site → API demo panel: hosts