billingHelp

Architecture and the platform overview

How one installation is put together — webroot, application, data, database users, providers, email, scheduler — and what the Platform overview shows.

Architecture of one installation Browsers reach Nginx, which serves the webroot (public/: entry files, assets, static SEO files) and passes PHP requests to PHP-FPM. PHP runs the application in app/ (core, providers, views, help content), which is never served. app/ reads and writes data/ (config.php, master key, uploads, GeoIP files, backups, logs, cache) and the MariaDB database through three database users: app (data changes only), backup (read and lock) and migrate (schema). Outbound, the application calls the payment providers' APIs and SMTP2GO for email. Inbound, the providers deliver signed webhooks to public/webhooks/. A system cron job, or the built-in pseudo-cron, runs the scheduled jobs. Browserscustomers, staff Payment providerssigned webhooks in Your server Nginx + PHP-FPMTLS, static files public/ (webroot)entries, assets, robots, sitemap app/ — never servedcore · providers · views · help content · jobs · tests data/config.php · keys/master.keyuploads · geo · backupslogs · cache MariaDBapp user: data onlybackup user: read + lockmigrate user: schema Provider APIsStripe, PayPal, … SMTP2GOemail out cronor pseudo-cron
Architecture of one installation
Text description

Browsers reach Nginx, which serves the webroot (public/: entry files, assets, static SEO files) and passes PHP requests to PHP-FPM. PHP runs the application in app/ (core, providers, views, help content), which is never served. app/ reads and writes data/ (config.php, master key, uploads, GeoIP files, backups, logs, cache) and the MariaDB database through three database users: app (data changes only), backup (read and lock) and migrate (schema). Outbound, the application calls the payment providers' APIs and SMTP2GO for email. Inbound, the providers deliver signed webhooks to public/webhooks/. A system cron job, or the built-in pseudo-cron, runs the scheduled jobs.

Three directories#

DirectoryContainsServed?
public/Entry files (index.php, admin/, pay/, account/, super/, api/, help/, webhooks/), assets, robots.txt, sitemap.xml, llms.txt, faviconYes — this is the Nginx root
app/All PHP code, views, help pages, fonts for images, tests, toolsNever
data/config.php, keys/master.key, uploads, GeoIP files, licensed downloads, backups, logs, cacheNever

The application needs no rewrite rules. With the hardened vhost's try_files … /index.php, links are clean (/admin/settings/users); on a plain PHP vhost they use the entry files (/admin/?r=settings/users). The application notices which one works and builds its links to match.

How a request is handled#

How a request is handled A request reaches a physical entry file (index.php, or admin/index.php and the other area entries on a plain vhost). The kernel boots the application and the router finds the route in one route table, for clean URLs and for the ?r= form alike. The route's rules run next: sign-in for the right area (super admin, workspace member, customer, API key), the role's capability, and the CSRF and origin check on every change. The controller does the work and renders a view. Every response leaves with the security headers (CSP with a nonce, HSTS, frame and referrer rules, robots) and, on public pages, a cookieless page-view pixel. Pseudo-cron runs after the response is sent. Entry fileindex.php orarea/index.php Routerone route table/path or ?r=path Route rulessign-in · roleCSRF + origin Controllerwork + viewtenant-scoped DB ResponseCSP nonce, HSTS, robotspage-view pixel (public) Refusedsign-in page, 403, 404 pseudo-cron after sending
How a request is handled
Text description

A request reaches a physical entry file (index.php, or admin/index.php and the other area entries on a plain vhost). The kernel boots the application and the router finds the route in one route table, for clean URLs and for the ?r= form alike. The route's rules run next: sign-in for the right area (super admin, workspace member, customer, API key), the role's capability, and the CSRF and origin check on every change. The controller does the work and renders a view. Every response leaves with the security headers (CSP with a nonce, HSTS, frame and referrer rules, robots) and, on public pages, a cookieless page-view pixel. Pseudo-cron runs after the response is sent.

Every workspace-owned row carries the workspace id. The data layer adds it to every query from the signed-in context, so no screen builds its own workspace filter. Only super admins and system jobs can open a cross-workspace handle, and each use is logged.

How a webhook is handled#

How a provider webhook is processed The provider posts an event to /webhooks/provider.php with the credential set in the query string (Authorize.net: no query string; the set is found by its signature key). The signature is checked on the raw body before anything is parsed or stored; a bad signature is refused. The event id is recorded once, so duplicates are ignored. The object is fetched again from the provider's API. The state machine applies the change if it is allowed; a stale or out-of-order event is kept but not applied. Then emails, outbound webhooks and analytics follow. If processing fails the endpoint answers 500 and the provider retries. ProviderPOST event Verify signatureraw body, first Deduplicateevent id once Re-fetchfrom the API State machineapply or keep (stale) Refused400 bad signature Thenemails, outbound webhooks Failure → 500the provider retries later
How a provider webhook is processed
Text description

The provider posts an event to /webhooks/provider.php with the credential set in the query string (Authorize.net: no query string; the set is found by its signature key). The signature is checked on the raw body before anything is parsed or stored; a bad signature is refused. The event id is recorded once, so duplicates are ignored. The object is fetched again from the provider's API. The state machine applies the change if it is allowed; a stale or out-of-order event is kept but not applied. Then emails, outbound webhooks and analytics follow. If processing fails the endpoint answers 500 and the provider retries.

Three database users#

  • app — reads and changes data, table by table; it can only add to the audit log, never change or delete it.
  • backup — reads and locks, for the nightly dump.
  • migrate — owns the schema, applies migrations and maintains the app user's grants.

The Platform overview#

The overview shows, at a glance:

  • System — version, database, disk, scheduler and the latest self-check result, each linking to its screen;
  • Backups — the newest archive's age, the latest restore drill, and whether an off-box copy is recent;
  • Tenants — active, awaiting their owner, suspended, with the newest ones listed;
  • Credential sets by provider across all workspaces;
  • Recent activity from the audit log.