badges/shields

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