Architecture Overview

Relevant source files

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

• AGENTS.md
• README.md
• src/services/versions/v1/index.ts
• src/services/stats/v1/index.ts
• test/lib/middleware.test.ts
• test/integration/app.test.ts

The FOSSBilling API Worker serves as the central hub for FOSSBilling instances, providing critical services such as version checks, update management, system-wide alerts, and release statistics. Built on the Hono framework, the architecture is designed to be lightweight, fast, and platform-agnostic, though it is primarily deployed as a Cloudflare Worker.

Sources: README.md:3-8, AGENTS.md:5-9

Core Architectural Principles

The project follows a modular, layered approach to separate business logic from infrastructure. This separation ensures that core features remain runtime-agnostic and can be tested or deployed across different environments (e.g., Cloudflare, Node.js) with minimal changes.

Layered Structure

• Application Logic: Feature-specific modules (e.g., Versions, Central Alerts, Stats) located in src/services/.
• Platform Layer: Interfaces for infrastructure components like Cache, Databases, and Environment variables in src/lib/.
• Adapters: Implementation-specific code for different runtimes, such as src/lib/adapters/cloudflare (D1 and KV) or src/lib/adapters/node.

Sources: README.md:15-22, AGENTS.md:5-9

System Components

The API is divided into three primary services, each handling a specific domain of the FOSSBilling ecosystem.

Component Map

Component	Responsibility	Primary Data Sources
Versions Service	Manages release data, changelogs, and update refresh logic.	GitHub API, CACHE_KV, AUTH_KV
Central Alerts	Provides critical notifications to FOSSBilling installations.	DB_CENTRAL_ALERTS (D1)
Stats Service	Aggregates and visualizes release metrics (size, PHP requirements).	Versions Service, CACHE_KV

Sources: README.md:10-14, AGENTS.md:36-42, src/services/stats/v1/index.ts:16-18

Middleware and Context

The system utilizes a platformMiddleware to inject infrastructure bindings (databases, caches) into the Hono context. This allows services to access Cloudflare resources like D1 and KV without direct dependencies on the Cloudflare global environment.

Data Flow: Versions and Stats

The Versions Service acts as a data provider for the Stats Service. Both services utilize a multi-tiered caching strategy to optimize performance and handle GitHub API rate limits.

Release Fetching Logic

The getReleases function handles the retrieval of release information. It first checks the CACHE_KV for existing data. If missing or forced by an /update call, it fetches data from the GitHub REST API and augments it with metadata (like PHP versions) fetched via the GitHub GraphQL API.

Stats Aggregation

The Stats Service reuses the getReleases logic to build visualization datasets. It aggregates raw release data into metrics such as patches per release line and releases per year.

Sources: src/services/stats/v1/index.ts:74-120

Security and Authentication

Administrative actions, specifically the /update endpoint which refreshes the cache from GitHub, require Bearer token authentication.

• Token Storage: The UPDATE_TOKEN is stored in the AUTH_KV namespace.
• Caching: To reduce KV lookups, the token is cached in memory with a 60-second TTL (UPDATE_TOKEN_CACHE_TTL_MS).
• Authorization: Handled via Hono's bearerAuth middleware.

Sources: src/services/versions/v1/index.ts:30-47, src/services/versions/v1/index.ts:143-150

Storage Configuration

The architecture relies on specific Cloudflare bindings defined in the platform layer.

Binding Name	Type	Purpose
DB_CENTRAL_ALERTS	D1	Stores persistent alert messages for the project.
CACHE_KV	KV	Caches GitHub API responses to prevent rate limiting.
AUTH_KV	KV	Stores the UPDATE_TOKEN for administrative tasks.
GITHUB_TOKEN	Secret	GitHub Personal Access Token for repository access.

Sources: README.md:38-48, AGENTS.md:58-61

Conclusion

The FOSSBilling API Worker architecture prioritizes modularity and performance through effective caching and a clean separation between business logic and the Cloudflare runtime. By leveraging Hono's middleware and a tiered storage approach (D1 for persistence, KV for caching), the system provides a robust backbone for the FOSSBilling instance ecosystem.