# Hostledger

A self-hosted client billing, provisioning, and support platform for hosting
companies — a sellable, installable alternative to WHMCS. Built in PHP +
MySQL so it installs on any standard cPanel account, the same way WHMCS does:
upload the files, create a MySQL database, run the install wizard.

Developed by the SEO Boost Hosting team.

(Previously scaffolded under the working name "HostBill" — renamed because
HostBill is already a real, established competitor product at
hostbillapp.com. "Hostledger" was checked and has no known collision.)

## Status

Feature-complete — see `PROJECT_PLAN.md` for the full phase-by-phase build
checklist and `CHANGELOG.md` for the current version's known gaps. **Not yet
run against a real PHP/MySQL server** (the build environment had neither) —
run the install wizard and a full lifecycle test on a real cPanel account
before relying on this for real billing. See `PROJECT_PLAN.md` Phase 11.

## What it does

- Client billing: plans/products, orders, invoices, recurring renewals,
  overdue handling.
- Payments: Stripe, PayPal, and Paystack, each pluggable — paste API keys
  into Admin → Gateways and enable, no code changes.
- Hosting provisioning: automatic cPanel account creation/suspension via
  WHM's API once an invoice is paid.
- Domains: live availability search and pay-then-register flow via eNom.
- Affiliate program: referral codes, commission tracking, payout recording.
- Support tickets with email notifications.
- Admin and client self-service portals with dashboards.

## Folder map

```
Hostledger/
├── install/       Web-based install wizard (requirements check, DB setup,
│                  admin account creation). Locks itself after install.
├── admin/         Staff-facing control panel (clients, products, invoices,
│                  services, tickets, servers, gateways, registrars, settings).
├── client/        Customer-facing self-service portal (order, pay, tickets).
├── includes/      Bootstrap, DB connection, session/auth helpers, config.
├── classes/       Core logic: Billing, Auth, Crypto, Mailer, WHM client, etc.
│   ├── Gateways/  GatewayInterface + Stripe/PayPal/Paystack implementations.
│   └── Registrars/ RegistrarInterface + EnomRegistrar.
├── cron/          Scripts wired into cPanel's Cron Jobs (renewals, dunning,
│                  domain expiry reminders).
├── api/           webhooks.php — payment gateway webhook entrypoint.
├── database/      schema.sql — the full DB schema, run by the installer.
├── scripts/       build-release.sh — produces a clean distributable zip.
├── templates/     Unused (scaffolded early; includes/layout.php inlines CSS).
├── assets/        css/js/img served to the browser — drop assets/img/logo.png
│                  here to have it picked up automatically in the topbar.
├── storage/       Writable at runtime: logs/, cache/. Not web-executable.
└── docs/          INSTALL.md and other docs for end users buying this.
```

## Design constraints (so every phase stays compatible with "installs on any cPanel")

- **PHP only, no Composer/CLI dependency at runtime.** Shared hosting cPanel
  accounts don't reliably give you SSH or `composer install`. Every
  third-party integration (Stripe, PayPal, Paystack, eNom, WHM) is
  hand-written against the plain REST/XML API with cURL, never a Composer
  package.
- **MySQL via PDO**, using a configurable table prefix so it can share a
  database with other applications if needed (WHMCS convention).
- **No root/SSH assumptions.** Only used APIs: cPanel's own PHP runtime,
  MySQL, and outbound cURL to the gateways/registrar/WHM (WHM API access
  itself requires a token from a server the buyer controls — that's
  expected, since provisioning hosting accounts is the whole point).
- **Cron via cPanel's Cron Jobs UI**, calling PHP scripts directly
  (`php /home/user/hostledger/cron/billing.php`) — no persistent daemon.

## See also

- `PROJECT_PLAN.md` — full phased build checklist, kept in sync as work continues.
- `CHANGELOG.md` — version history and known gaps.
- `docs/INSTALL.md` — end-user cPanel installation guide.
