Skip to content

GitHub README Counter

apiLast commit

Express service that increments a file-backed counter and returns the current value as a customizable SVG image.

Open productSource
Role
API design and backend engineering
Scope
HTTP delivery, state management, and SVG generation
Status
Publicly deployed

Problem

README authors need an image-embeddable counter endpoint because Markdown cannot run application JavaScript or call an API and render arbitrary data directly.

Constraints

  1. C1

    Requests from bots, caches, renderers, and refreshes are counted, so values are not unique-human analytics.

  2. C2

    File persistence is single-process and can reset on ephemeral filesystems.

  3. C3

    The endpoint has no authentication or documented rate limiting.

Architecture

Express routes and query validation; in-memory/file counter store; escaped dynamic SVG renderer plus JSON health endpoint.

01

HTTP service

Express routes and query validation.

02

State

In-memory/file counter store.

03

SVG response

Escaped dynamic SVG renderer plus JSON health endpoint.

Decisions

D1

Return SVG

Return SVG so the result embeds in standard Markdown.

D2

Use simple file persistence

Use simple file persistence, trading horizontal scalability/durability for easy self-hosting.

D3

Describe the value as request count

Describe the value as request count rather than visitor count.

Contribution

  • Implemented named counter increment/read behavior.
  • Built configurable escaped SVG output.
  • Added health/status/uptime reporting.
  • Documented embedding, configuration, persistence, and deployment limitations.

Outcomes

  • Users can self-host an embeddable counter.
  • Customize the generated badge.
  • Keep separate counters by identifier.
  • Monitor basic process health.

Verified stack

  • Node.js
  • Express.js
  • JavaScript
  • SVG
  • System Design

Working through something similar?

Share your challenge, scope, and timeline to start a focused conversation.