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

This directory should be writable by the web server.

`/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 API files including the JavaScript wrapper (API.js). See the wrapper docs.

`/src/library/Box`

Legacy classes inherited from BoxBilling. Contains:

Translation utilities
Exception handling
Twig extensions
Various tools

These are gradually being modernized.

`/src/library/FOSSBilling`

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

`/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.

`/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
├── html_admin/         # Admin panel templates
├── html_client/        # Client area templates
├── html_email/         # Email templates
├── manifest.json       # Module metadata
└── Service.php         # Business logic (not exposed via API)

Guide: Creating a Module

`/src/themes`

All installed themes.

Theme structure:

theme-name/
├── assets/             # CSS, JS, images
├── config/
│   └── settings.html.twig   # Theme settings UI
├── html/               # Twig templates
│   └── layouts/        # Base layouts
├── html_custom/        # User overrides (not for theme files)
└── 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.