Penguin Statistics - V3 Backend

The re-designed Penguin Statistics v3 Backend, built with Go.

Using the data

The drop data is public:

• REST API at https://penguin-stats.io/PenguinStats/api/v2/: see the developer docs and the OpenAPI (Swagger 2.0) spec.

• MCP server for AI assistants (Claude, ChatGPT, Cursor, VS Code, Cherry Studio and others) at https://mcp.penguin-stats.io/mcp: Streamable HTTP, no authentication, read-only. In Claude Code:

  claude mcp add --transport http --scope user penguin-stats https://mcp.penguin-stats.io/mcp
  

  The steps for every other app, in English and Chinese, are at https://mcp.penguin-stats.io/.

• Plugin and skill for coding agents, the MCP server with a skill on reading, citing and querying the numbers: https://github.com/penguin-statistics/agent-skills

The drop data is licensed CC BY-NC 4.0: non-commercial use, with credit. Credit it as Data: Penguin Statistics (penguin-stats.io), CC BY-NC 4.0. The code of this repository is MIT.

Architecture

This Go project mainly uses:

• gofiber/fiber
• uber-go/fx
• uptrace/bun

This project mainly follows a RESTful API design.

Operations

Report tasks in the dead-letter stream

The report worker moves a report task out of the penguin-reports stream into penguin-reports-dead (subjects REPORT_DEAD.*) when it can never be processed (it is not a task, or a stage of it does not exist) or when it failed at each of its 30 deliveries, which take about 97 minutes of retry delays. Each move is logged at error level (reportwkr.malformed, reportwkr.parked or reportwkr.dead). The copy keeps the payload as published, with these headers:

• Penguin-Original-Subject: the subject it was published under, like REPORT.SINGLE
• Penguin-Original-Sequence: its sequence in penguin-reports
• Penguin-Deliveries: its deliveries when it moved
• Penguin-Last-Error: the error that moved it

A task too close to the maximum payload to fit with these headers moves without them, and its subject under REPORT_DEAD.* names its original subject; its move is logged as reportwkr.dead.bare, with the sequence and the error.

Nothing in the stream expires. With the nats CLI, once the cause is fixed:

# list the tasks, with their headers
nats stream view penguin-reports-dead
# show one, by its sequence in penguin-reports-dead
nats stream get penguin-reports-dead 42
# replay it under its original subject: the worker

... [View full README on GitHub](https://github.com/penguin-statistics/backend-next#readme)