EZSCALE/website
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(claude): expand strategic direction + sister-project context

Browse Source 
Adds two sections to the project-level CLAUDE.md:

- "Strategic Direction: WHMCS Replacement" — scopes the long-arc plan
  (storefront, billing, provisioning, customer area, marketing site,
  admin RBAC, notifications, marketing email automation, future
  registrar / SSL / multi-tenant / partner API) so future sessions
  don't accidentally re-litigate decisions.

- "Sister Projects (Reference)" — calls out infrastructure/ (Ezra +
  capacity / costs source-of-truth) and ezscale_api/ (Battlelog/ACP
  SaaS) as separate Gitea repos with their own CLAUDE.md, plus the
  catalog-data flow (website pulls hardware inventory + IP
  availability from infrastructure/).

Also clarifies cross-repo conventions: Gitea (not GitHub), no shared
DBs, design docs under docs/superpowers/specs/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Murray
2026-04-26 22:11:11 -04:00
parent 39149f0b30
commit 8a984f86ad
1 changed files with 62 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
CLAUDE.md
View File

@@ -4,15 +4,16 @@
EZSCALE Site — Laravel 12 application for VPS/Dedicated Server hosting management (billing, subscriptions, provisioning, customer management, SSO).
## Phase Tracking (MANDATORY)
All work MUST be tracked against GitHub issues and `TASKS.md`:
All work MUST be tracked against Gitea issues and `TASKS.md`. **Use Gitea MCP tools (`mcp__gitea__*`) — never `gh` CLI.**
1. **Before starting:** Check the relevant GitHub issue (`gh issue list`) and `TASKS.md` for current status.
2. **While working:** Update the GitHub issue with progress comments (`gh issue comment <number> --body "Completed X"`).
3. **After completing:** Update `TASKS.md` to check off completed items and close the corresponding GitHub issue.
1. **Before starting:** Check the relevant Gitea issue (`mcp__gitea__list_issues` for repo `EZSCALE/website`) and `TASKS.md` for current status.
2. **While working:** Update the Gitea issue with progress comments (`mcp__gitea__add_issue_comment`).
3. **After completing:** Update `TASKS.md` to check off completed items and close the corresponding Gitea issue.
4. **New tasks discovered:** Create sub-issues or add items to `TASKS.md` immediately.
5. **Commit messages:** Reference the GitHub issue number (e.g., `Fix checkout validation (#3)`).
5. **Commit messages:** Reference the Gitea issue number (e.g., `Fix checkout validation (#3)`).
GitHub issues: https://github.com/EZSCALE/accounting/issues
Gitea repo: https://git.ezscale.cloud/EZSCALE/website
Gitea issues: https://git.ezscale.cloud/EZSCALE/website/issues
## Documentation Updates (MANDATORY)
When a phase or significant task is finished, update: `TASKS.md`, GitHub issues, `CLAUDE.md`, memory files, and `PROJECT_DEVELOPMENT.md` (if architecture changed).
@@ -172,6 +173,61 @@ google-chrome --headless=new --disable-gpu --no-sandbox --screenshot=/tmp/screen
4. **Admin Panel** — Dashboard, analytics, user/service management
5. **SSO** — Single sign-on via Laravel Passport
## Strategic Direction: WHMCS Replacement
This app is being built into a full WHMCS replacement for EZSCALE. Scope to track:
- **Storefront / catalog** — product browsing, configurable options, cart, checkout, multi-currency, quotes, coupons, tax (regional)
- **Billing** — subscriptions, invoices, dunning, credit balances, refunds, Stripe + PayPal (more gateways later)
- **Provisioning** — VirtFusion / SynergyCP / Enhance / Pterodactyl modules (idempotent, retry, suspension/termination hooks)
- **Customer area** — services list, KB, ticketing, login history, two-factor, affiliate dashboard, credits
- **Marketing site** — pricing, status page, blog, lead capture, affiliate landing pages
- **Admin panel** — RBAC staff, financial reports, fraud detection, dunning queue, manual invoice ops, refund flows
- **Notifications** — transactional email, Discord webhooks, Slack handoff to Ezra (see `infrastructure/`)
- **Marketing email automation** — drip campaigns, lifecycle/winback, broadcast announcements, segmented lists (lead/customer/lapsed), unsubscribe + preference center, deliverability hooks (Stalwart). *Active planning.*
- **Future** — domain registrar integration, SSL provisioning, reseller multi-tenancy (see `KASM_AND_MULTITENANCY.md`), API for partner integrations
When planning new work, check what's already shipped (recent commits cover KB, tickets v2, multi-currency, cart, quotes, affiliates, credits, staff RBAC, fraud detection, service panels, churn prevention, login history, financial reports, configurable checkout). Gap-analyze against WHMCS feature parity before building.
## Sister Projects (Reference)
The EZSCALE platform is split across three repositories, all on Gitea (`git.ezscale.cloud`). Read their `CLAUDE.md` files when touching cross-repo concerns; do not modify them from this repo.
**Catalog data model:** website/ owns the product catalog (SKUs, pricing, configurable options, descriptions). It *pulls* from various sources to populate inventory and capacity dynamically — most notably from `infrastructure/` for the VPS and dedicated server lineups. Treat infrastructure/ as the source-of-truth for hardware inventory, capacity, and rack reality; treat website/ as the source-of-truth for what's *for sale*, at what price, and to whom.
### `../infrastructure/` — Ops platform & Ezra AI agent
**Path:** `/home/andrew/local_projects/infrastructure/` · **Repo:** `git@git.ezscale.cloud:EZSCALE/infrastructure.git`
Houses everything that runs the *business* (not the storefront): K3s clusters (US/EU), Terraform-managed Cloudflare DNS, Ansible playbooks, the `web/` Laravel 13 admin panel that hosts **Ezra** (the AI ops agent — capacity scoring, MRR forecasting, ticket sync, customer intelligence, investor reports), plus deep reference docs.
**What website/ pulls from infrastructure/ (catalog inputs):**
- **VPS lineups** — VirtFusion package definitions, hypervisor capacity, plan availability per region. Source: `infrastructure/web/app/Services/ApiClients/VirtFusion*` + `Services/Capacity/`. Use to drive the `/vps` product pages and "stock available" indicators.
- **Dedicated server lineups** — SynergyCP inventory + the rack reality in `infrastructure/docs/reference/rack-atl.md` (server SKUs, specs, current allocations). Use to drive the `/dedicated` product pages.
- **Vendor costs / margins** — `infrastructure/docs/reference/business-costs.md` (Evocative, Hetzner, etc.). Reference when setting prices; never expose to customers.
- **IP availability** — `infrastructure/docs/reference/ip-resources.md` (ARIN vs Evocative leases). Drives whether IPv4 add-ons can be sold without a waitlist.
**Other intersections (non-catalog):**
- **API client patterns** — `infrastructure/web/app/Services/ApiClients/BaseApiClient` provides retry, rate-limit, and IPv4 DNS pinning. Port that base class here when our provisioning clients need the same hardening.
- **Customer intelligence** — `Services/Intelligence/` syncs scoring/segmentation. Website billing events should feed this; risk scores from it should drive fraud thresholds here.
- **Ticketing** — Ezra ingests SupportPal tickets and drafts AI responses. As website/ takes over ticketing, agree on a sync contract (or have Ezra read from our DB).
- **Reverse DNS / mail** — `Services/Rdns/` (PowerDNS) and Stalwart/SOGo. Customer rDNS requests in the account panel should flow through Ezra, not direct PowerDNS calls.
- **Identity** — Authentik IdP at `id.ezscale.cloud`. Staff SSO should integrate via SocialiteProviders/Authentik (already used in `infrastructure/web/`); customers stay on Fortify + Passport.
- **Other reference docs** — `powerdns.md`, `mail-server.md`, `authentik.md`, `llc-agreement.md`, `zfs-storage.md`, `uptime-kuma.md`, `hardware-monitoring.md`.
### `../ezscale_api/` — Battlelog/ACP SaaS API
**Path:** `/home/andrew/local_projects/ezscale_api/` · **Repo:** `git@git.ezscale.cloud:EZSCALE/api.git` · **Endpoint:** `api.ezscale.cloud`
Centralized Laravel 12 API at `api.ezscale.cloud` that fronts Battlelog (BF3/BF4/BFH) for the **ACP (Adkats Control Panel)** product — game-server admin SaaS sold to Battlefield community server operators. TimescaleDB-backed, single shared API key, multi-tenant ACP instances consume it.
**Key intersections with website/:**
- **As a product** — ACP is one SKU in the website catalog. When provisioning ACP, website calls into the ACP tenant orchestrator (separate from this API) but tenants in turn need the API key issued/revoked here.
- **API key lifecycle** — Currently a single static `EZSCALE_API_KEY`. When website starts selling ACP plans with usage limits, we'll likely need per-tenant keys here — coordinate before changing the auth model.
- **Real-time pattern** — Standalone Node.js Socket.IO + Redis pub/sub setup (`ezscale_api/socketio/`) is a reusable template if website needs live admin dashboards beyond polling.
- **Helm/K8s deployment template** — `ezscale_api/helm/ezscale-api/` is the cleanest deploy reference for our eventual K8s migration of website/.
### Cross-repo conventions
- **Git host:** Gitea at `git.ezscale.cloud` (NOT GitHub). Use `mcp__gitea__*` tools, never `gh` CLI for these repos.
- **DB hosts:** Each app has its own DB. Cross-repo data access is via HTTP APIs, never shared DB connections.
- **Docs format:** Each repo's `CLAUDE.md` is the canonical onboarding doc. `docs/superpowers/specs/` holds design docs; `docs/reference/` (in infrastructure) holds long-lived ops reference.
## Reference Docs
- `TASKS.md` — Task list and progress tracking
- `PROJECT_DEVELOPMENT.md` — Architecture decisions, database schema, API integrations