Project Structure

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/integration/app.test.ts
• package.json

The FOSSBilling API is a lightweight service built on the Hono framework, designed to function as the central hub for FOSSBilling instances. Its primary purpose is to manage version checks, provide update information, broadcast system-wide alerts, and visualize release statistics. While currently deployed on Cloudflare Workers, the architecture is intentionally platform-agnostic to support alternative runtimes like Node.js.

Sources: README.md:3-8, AGENTS.md:7-12

Core Architecture

The project follows a modular design that separates feature logic from platform-specific implementations. This separation ensures that the core application remains runtime-agnostic, facilitating testing and deployment across different environments.

Directory Organization

Directory	Description
src/app/	Worker entrypoint and route wiring for the Hono application.
src/services/	Contains feature-specific logic (e.g., versions/v1, stats/v1).
src/lib/	Platform interfaces, adapters (Cloudflare, Node), and shared utilities like logging.
test/	Test suites mirroring the src layout, including integration tests and mocks.

Sources: AGENTS.md:7-12, README.md:20-27

Logic Separation

The architecture distinguishes between three primary layers:

1. Application Logic: Feature modules located in src/services/ that operate without knowledge of the underlying runtime.
2. Platform Layer: Interfaces in src/lib/ defining abstractions for Caching, Databases, and Environment variables.
3. Adapters: Implementation of platform interfaces, such as the Cloudflare adapter using KV and D1, and the Node adapter for testing.

Sources: README.md:20-27

Service Modules

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

Versions Service (/versions/v1)

This module serves as the source of truth for updates. It interacts with the GitHub API to fetch release data, which is then processed and cached in Cloudflare KV. It includes logic for semantic version comparison and changelog consolidation.

Key components include:

• getReleases(): Fetches and parses GitHub releases, including a GraphQL batch fetch for PHP requirements.
• loadReleases(): Orchestrates release loading with optional cache updates.
• registerCachedRoute(): A helper to apply standard middleware (ETag, PrettyJSON, Cache-Control) to versioning endpoints.

Sources: src/services/versions/v1/index.ts:47-60, src/services/versions/v1/index.ts:258-290, README.md:30-38

Stats Service (/stats/v1)

The Stats service provides visualization data for FOSSBilling releases. It reuses data from the Versions service to generate aggregated metrics.

• Data Aggregation: Aggregates statistics such as release sizes, PHP version requirements over time, and releases per year.
• Visualizations: Provides an HTML endpoint that renders charts using Chart.js.

Sources: src/services/stats/v1/index.ts:81-125, AGENTS.md:46-52

Storage and Configuration

The project utilizes Cloudflare-specific storage solutions, abstracted via the platform layer.

Component	Binding Name	Purpose
D1 Database	DB_CENTRAL_ALERTS	Persistent storage for critical alert messages.
KV Namespace	CACHE_KV	Caching GitHub API responses and stats data (24h TTL).
KV Namespace	AUTH_KV	Secure storage for the UPDATE_TOKEN used in cache refreshes.

Sources: README.md:42-53, src/services/stats/v1/index.ts:24-27

Development and Tooling

The project uses modern TypeScript tooling for development, testing, and deployment.

• Runtime: Cloudflare Workers (via Hono).
• Testing: Vitest is used for both unit and integration tests. Integration tests verify the full request/response cycle and cross-service communication.
• Deployment: Wrangler is utilized for local development (npm run dev) and production deployment (npm run deploy).
• Environment: Secrets like GITHUB_TOKEN are managed via .dev.vars locally and Wrangler secrets in production.

Sources: package.json:7-20, AGENTS.md:14-25, test/integration/app.test.ts:45-75

Summary

The FOSSBilling API project structure emphasizes a clean separation between application logic and infrastructure. By centralizing core functionality in src/services/ and abstracting platform details in src/lib/, the system maintains high testability and flexibility for future deployment environments while providing robust versioning and statistics services to the FOSSBilling community.

Sources: README.md:18-27, AGENTS.md:7-12