The visible feature was only the surface
README authors need an image-embeddable counter endpoint because Markdown cannot run application JavaScript or call an API and render arbitrary data directly.
The system also had to respect concrete constraints. Requests from bots, caches, renderers, and refreshes are counted, so values are not unique-human analytics. File persistence is single-process and can reset on ephemeral filesystems. The endpoint has no authentication or documented rate limiting.
My role covered api design and backend engineering, with responsibility for http delivery, state management, and svg generation.
I turned the constraints into boundaries
Express routes and query validation; in-memory/file counter store; escaped dynamic SVG renderer plus JSON health endpoint.
Return SVG so the result embeds in standard Markdown.
Use simple file persistence, trading horizontal scalability/durability for easy self-hosting.
Describe the value as request count rather than visitor count.
The key decision: Return SVG.
The implementation had to prove the model
I delivered the work across the full path: Implemented named counter increment/read behavior. Built configurable escaped SVG output. Added health/status/uptime reporting. Documented embedding, configuration, persistence, and deployment limitations.
The result is concrete: Users can self-host an embeddable counter. Customize the generated badge. Keep separate counters by identifier. Monitor basic process health.
The senior engineering lesson was that solving the visible workflow is only half the job. The architecture must also make constraints, failure modes, evidence, and ownership explicit enough for the next change to remain safe.