FOSSBilling File Structure

FOSSBilling's structure can feel unusual if you are coming from modern frameworks like Laravel or Symfony. This guide shows where the main pieces live and what each directory is responsible for.

Source Code

All source code lives in the /src directory.

`/src/data`

Runtime data storage:

Cache — Compiled templates, API responses
Logs — Application logs and error logs
Uploads — User-uploaded files (/data/uploads)

This directory should be writable by the web server.

`/src/public`

Public core assets that must be web-accessible:

Assets — Shared built browser assets (/public/assets), including the API wrapper, shared runtime, Markdown CSS, and CKEditor bundle
Branding — Default logo, dark logo, and favicon (/public/branding)
Gateway icons — Payment gateway logos (/public/gateways)

`/src/install`

The installation wizard. Automatically deleted after installation unless APP_ENV=dev is set.

`/src/library`

Core PHP classes and business logic.

`/src/library/Api`

Core PHP API files. The browser-side API wrapper source now lives in /frontend/core/api.js and builds to /src/public/assets/js/api.js. See the wrapper docs.

`/src/library/Box`

Legacy compatibility classes. Most have been migrated to FOSSBilling/:

File	Status
`Box/Translate.php`	Still present

These are gradually being modernized.

`/src/library/FOSSBilling`

New or rewritten classes specific to FOSSBilling. This is where active development happens.

Subdirectory	Purpose
`Doctrine/`	Doctrine DBAL and ORM factory classes (pairs with RedBean for a dual-ORM approach)
`Http/`	`RequestFactory`, `CsvResponseFactory`, HTTP exception handling
`Security/`	`RateLimiter`, `RateLimitResult`, `AuthenticationRequiredException`, `RandomizedTimeFloor`
`Sanitizer/`	`BrowserHtmlSanitizer` (HTML sanitization via Symfony)
`Twig/`	`TwigFactory`, `TwigLoader`, `SandboxedStringRenderer`, custom Twig extensions and filters. See Twig Filters & Functions for the template-facing API.
`Validation/`	API validation utilities

Key standalone files:

Module.php — Base class for modules
Paginator.php — Pagination utility

`/src/library/Model`

Database models. You typically won't edit these, but they're useful for understanding the data structure.

`/src/library/Payment`

Payment gateway adapters. If you're building a payment gateway, look in /src/library/Payment/Adapter/.

Guide: Creating a Payment Gateway

`/src/library/Registrar`

Domain registrar adapters for domain reselling. Check /src/library/Registrar/Adapter/.

Guide: Creating a Registrar Integration

`/src/library/Server`

Server manager adapters for hosting control panels (cPanel, Plesk, HestiaCP, etc.).

Guide: Creating a Server Manager

`/src/locale`

Translations as a Git submodule. Pointing to github.com/FOSSBilling/locale.

`/frontend`

Shared frontend source and build tooling:

Path	Purpose
`core/`	Shared browser runtime and API wrapper source
`editor/`	CKEditor integration source
`styles/`	Shared CSS such as Markdown rendering styles
`tools/`	Common esbuild, Sass, PostCSS, asset copy, and PurgeCSS helpers used by theme builds

The root npm run build command builds this directory into /src/public/assets.

`/src/modules`

All modules live here. Each module is a self-contained unit of functionality.

A typical module structure:

ModuleName/
├── Api/
│   ├── Admin.php       # Admin API endpoints
│   ├── Client.php      # Client API endpoints
│   └── Guest.php       # Guest/public API endpoints
├── Controller/
│   ├── Admin.php       # Admin routes/controllers
│   ├── Client.php      # Client routes/controllers
│   └── Guest.php       # Guest routes/controllers
├── templates/          # Module templates
│   ├── admin/          # Admin panel templates
│   ├── client/         # Client area templates
│   └── email/          # Email templates
├── manifest.json       # Module metadata
└── Service.php         # Business logic

Guide: Creating a Module

`/src/themes`

All installed themes.

Theme structure:

theme-name/
├── assets/                 # CSS, JS, images (built via esbuild)
│   └── build/              # Generated theme assets and manifest
├── config/
│   └── settings.html.twig  # Theme settings UI
├── html/                   # Twig templates
├── html_custom/            # User overrides (overrides take priority)
└── manifest.json           # Theme metadata

The html_custom/ folder lets users override templates without editing the theme directly.

Guide: Creating a Theme

For assistance, join our Discord community.