Stats Service

Relevant source files

The following files were used as context for generating this wiki page:

• src/services/stats/v1/index.ts
• src/services/stats/v1/interfaces.ts
• AGENTS.md
• README.md
• test/services/stats/v1/index.test.ts

The Stats Service is a dedicated module within the FOSSBilling API designed to provide release statistics and visualizations for FOSSBilling versions. It acts as a data aggregator and visualization engine, processing release metadata to generate insights into project evolution, such as distribution size growth and PHP version requirement shifts.

The service provides two primary interfaces: a JSON data endpoint for programmatic consumption and a client-side rendered HTML dashboard using Chart.js. It reuses release data from the Versions Service and implements its own caching layer to minimize external API calls and ensure high performance.
Sources: AGENTS.md:68-75, src/services/stats/v1/index.ts:254-614

Architecture and Data Flow

The Stats Service is built on the Hono framework and designed to be runtime-agnostic, although it is primarily deployed on Cloudflare Workers. It follows a layered architecture where logic is separated from the platform-specific adapters (KV storage).

Core Components

• Data Aggregator (aggregateStats): Transforms raw release data into structured statistical categories.
• Cache Manager (getStats): Handles retrieval from CACHE_KV, corruption detection, and fresh fetching from the GitHub API via the Versions Service.
• Visualizer: A client-side HTML/JavaScript application that renders charts using Chart.js based on data from the API.

The following diagram illustrates the data flow from GitHub through the API to the end user:

API Endpoints

The Stats Service exposes two main routes under the /stats/v1 base path.

Endpoint	Method	Description
/	GET	Returns an HTML page with Chart.js visualizations.
/data	GET	Returns aggregated statistics in JSON format.

GET /stats/v1/data

This endpoint provides the raw statistical data used by the dashboard. The data is cached for 24 hours (86,400 seconds) by default.

Response Structure:
The response follows a standard envelope containing a result object with four main data arrays.

export interface StatsData {
  releaseSizes: ReleaseSizeData[];
  phpVersions: PhpVersionData[];
  patchesPerRelease: PatchesPerReleaseData[];
  releasesPerYear: ReleasesPerYearData[];
}

Sources: src/services/stats/v1/index.ts:16-19, src/services/stats/v1/interfaces.ts:1-6, test/services/stats/v1/index.test.ts:88-120

Data Aggregation Logic

The service processes raw release data using specific transformation rules to generate meaningful metrics:

1. Release Sizes: Converts bytes to Megabytes (MB), rounded to two decimal places.
2. PHP Requirements: Extracts the minimum_php_version for every release to track compatibility shifts.
3. Patches per Release: Aggregates versions into "lines" (e.g., 0.6.x) to count how many patches were released for each minor version.
4. Releases per Year: Extracts the year from the release timestamp to calculate project velocity over time.

Version Parsing

The service uses a helper function to normalize version strings into release lines for better grouping.

function parseVersionLine(version: string): string {
  const parts = version.split(".");
  if (parts.length >= 2) {
    return `${parts[0]}.${parts[1]}.x`;
  }
  return version;
}

Sources: src/services/stats/v1/index.ts:62-105

Caching Strategy

The service implements a multi-layer caching strategy to handle high traffic and GitHub API rate limits.

If the fresh fetch fails, the service can serve "stale" data from the cache if it exists, setting the stale flag to true in the response envelope.
Sources: src/services/stats/v1/index.ts:117-165, AGENTS.md:73-75

Configuration and Bindings

The Stats Service relies on specific environment variables and Cloudflare bindings defined in the project configuration.

Name	Type	Description
CACHE_KV	KV Namespace	Stores processed stats and raw GitHub responses.
GITHUB_TOKEN	Secret	Used to authenticate requests to the GitHub API.
STATS_CACHE_TTL	Constant	Default TTL of 86400 seconds (24 hours).
STATS_CACHE_KEY	Constant	Key name fossbilling-stats-data in KV storage.

Sources: src/services/stats/v1/index.ts:16-19, README.md:57-60

Summary

The Stats Service provides a specialized view of the FOSSBilling ecosystem by processing release metadata into digestible statistics. By utilizing the existing Versions Service infrastructure and a robust KV caching layer, it delivers both high-performance JSON data and an interactive HTML dashboard with minimal impact on external API rate limits.
Sources: src/services/stats/v1/index.ts:117-165, AGENTS.md:68-75