Architecture
Stacklane follows the structure of large cloud consoles. The frontend is a single-page application built on its own component library. It talks to a JSON API that is split by domain: identity, billing, cloud and so on. Everything is packaged as one process that hosting providers can install with apt.
browser ──HTTPS──▶ reverse proxy ──▶ stacklane (one binary)
├─ /api/iam identity, organizations, users, tokens, audit
├─ /api/cloud/v1 projects, regions, instances, SSH keys, tasks
├─ /api/hosting/v1 hosting plans and services
├─ /api/domains/v1 availability, registration, nameservers
├─ /api/billing/v1 credit, usage, invoices, payments, webhooks
├─ /api/support/v1 tickets
├─ /api/dns/v1 DNS zones and records (PowerDNS)
├─ /api/network/v1 signed DDoS detector events
├─ /api/admin back office for platform staff
└─ /* Angular portal, embedded at build time
SQLite (WAL) · secret key · SMTP
workers: instances · services · domains · billing
Identity model#
- Client (organization): owns resources, invoices and API tokens. Every user belongs to one client.
- Roles within a client:
administrator: full accessengineer: manages resourcesbilling: invoices and company detailsviewer: read only
- Platform staff:
owner,admin,billingandsupport. These users operate the hosting company's back office.
Authentication#
- Sign-in: returns a short-lived access token (JWT, HS256, signed with a key derived from the secret key) and sets a refresh cookie (
HttpOnly,SameSite=Strict,__Host-prefix on HTTPS). - Refresh: rotates the refresh secret on every use. A reused refresh token is rejected. Refresh and logout also require a same-origin
Originheader. - Session check: every access token names its session, and the session is checked on each request. Signing out or resetting a password takes effect immediately.
- Two-factor:
- The password step returns a single-use challenge with a limited number of attempts.
- TOTP steps are stored to prevent replay.
- Recovery codes are hashed and single use.
- API tokens: use
Authorization: APIKey <id>$<secret>. Only a SHA-256 hash of the secret is stored.
Audit and tracing#
Every mutation writes an audit record with the client, actor or token, source IP, user agent, event name and trace ID. The trace ID comes from an incoming W3C traceparent header when present, and is returned as X-Trace-Id.
Frontend#
@stacklane/uiprovides the design tokens (light and dark, configurable accent) and the components: button, field, card, badge, alert, dialog, dropdown, toast, pager, stat, empty state and icons.- The portal uses standalone components with signals and lazy-loaded feature routes.
- Translations are JSON files loaded at runtime.
- The production build is embedded in the Rust binary and served with a strict content security policy. The policy uses a nonce that changes on every request and allows no inline code beyond that.
Provisioning#
Long-running work goes through a task table. The API validates a request, records the resource and a task, and returns 202 Accepted with both. Three workers run inside the same process and claim tasks by resource type:
- instances: Proxmox VE clusters. Clone a cloud-init template, configure it, resize the disk and start it. Also power actions, firewall rule sync, snapshots (create, restore, delete), extra disks and deletion.
- services: cPanel/WHM, DirectAdmin and Pterodactyl. Create, suspend, unsuspend and terminate accounts.
- domains: Openprovider or a manual registrar. Register, renew and update nameservers. An hourly sweep renews domains from the credit balance.
Tasks that were running when the process stopped are marked as failed on start, so no operation is silently half-applied. The portal polls resources while they are in a transitional state.
Every integration sits behind a trait (Connector, Panels, Registrars, Gateways), so tests and the simulation mode use in-memory implementations.
Billing#
- Metering: every hour, the biller records usage for running and stopped instances and for active and suspended services. Each hour counts once per resource per month.
- Invoicing: on the first run of a new month, usage of the previous month is invoiced. The amount is prorated by hours, capped at the monthly price.
- VAT: decided per customer:
- the domestic rate in the seller's country
- reverse charge for EU businesses with a VAT ID
- the destination rate for EU consumers (One-Stop Shop)
- no VAT outside the EU
- Payments: credit is applied to new invoices automatically. Open invoices and top-ups are paid through a gateway or by bank transfer.
- Dunning: a reminder is sent after the due date. After the configured number of days, services are suspended and instances stopped. Once the invoice is paid, services are restored automatically and instances can be started again.
- Webhooks: treated as notifications only. The payment status is always fetched from the provider.
- Ledger: every balance change is recorded with the resulting balance.
Network protection#
- Instance firewalls: rules are stored in Stacklane and synchronized to the Proxmox VM firewall. Inbound traffic defaults to drop; outbound defaults to accept.
- DDoS: detection and mitigation run upstream, for example with FastNetMon and BGP. The detector reports
banandunbanevents for an IP address to a signed webhook. Stacklane maps the address to the instance that owns it, records the attack, shows it to the customer and can email them. - Panel: every API request is counted per source IP. Requests beyond the global concurrency limit are shed with
503instead of queueing. Request bodies are capped and requests time out after 30 seconds. Run Stacklane behind a reverse proxy and network-level DDoS protection for volumetric attacks.