Initial Ladill Give extraction — online giving pages at give.ladill.com.

Donation checkout via Ladill Pay (9% fee), church/giving QR pages, SSO, and platform scan forwarding. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-09 07:25:49 +00:00
commit 0860b08af7
295 changed files with 37190 additions and 0 deletions
@@ -0,0 +1,96 @@
+# Ladill Give — deploy & cutover runbook
+
+Standalone app for **online giving pages** at `give.ladill.com` — branded donation
+pages with collection categories (Offering, Tithe, Building Fund…). Donations
+settle into the one platform UserWallet (9% fee), then withdraw via
+`account.ladill.com`.
+
+Public scans stay at `ladill.com/q/<code>` (blueprint decision — printed codes
+never migrate). The platform host forwards church/giving codes to this app (see
+`GiveQrForwarder` on the monolith); grant the platform DB user read access:
+
+```bash
+sudo mysql -e "GRANT SELECT ON ladill_give.qr_codes TO 'ladilldb'@'127.0.0.1'; FLUSH PRIVILEGES;"
+```
+
+Set `GIVE_DB_*` on the platform `.env` if the lookup user differs from the
+main app DB user.
+
+---
+
+## 0. Prerequisites
+
+| Secret | Where |
+|---|---|
+| `LADILL_SSO_CLIENT_ID` / `LADILL_SSO_CLIENT_SECRET` | `passport:client` on platform |
+| `BILLING_API_KEY_GIVE` | platform `.env` + this app |
+| `PAY_API_KEY_GIVE` | platform `.env` + this app — Ladill Pay checkout (9% donations tier) |
+| `IDENTITY_API_KEY_GIVE` | platform `.env` + this app |
+| `PLATFORM_DB_*` | read `ladilldb.platform_settings` (Paystack keys from admin → Billing) |
+
+## 1. Gitea repo + CI
+
+1. Repo: **ladill-give** (create on Gitea)
+2. Push to `main` triggers `.gitea/workflows/deploy.yml`.
+3. App root: `/var/www/ladill-give`
+
+## 2. Server app-slot + database
+
+```bash
+sudo install -d -o deploy -g www-data /var/www/ladill-give
+sudo install -d -o deploy -g www-data /var/www/ladill-give/{releases,shared}
+sudo mysql -e "CREATE DATABASE ladill_give CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+sudo mysql -e "CREATE USER 'ladill_give'@'127.0.0.1' IDENTIFIED BY '<pw>';"
+sudo mysql -e "GRANT ALL ON ladill_give.* TO 'ladill_give'@'127.0.0.1'; FLUSH PRIVILEGES;"
+sudo mysql -e "GRANT SELECT ON ladilldb.platform_settings TO 'ladill_give'@'127.0.0.1'; FLUSH PRIVILEGES;"
+```
+
+## 3. Register OIDC client (platform)
+
+```bash
+php artisan passport:client \
+  --name="Ladill Give" \
+  --redirect_uri="https://give.ladill.com/sso/callback"
+```
+
+## 4. Platform integration
+
+```env
+BILLING_API_KEY_GIVE=<same>
+IDENTITY_API_KEY_GIVE=<same>
+PAY_API_KEY_GIVE=<same>
+RP_GIVE_FRONTCHANNEL_LOGOUT=https://give.ladill.com/sso/logout-frontchannel
+LADILL_GIVE_APP_URL=https://give.ladill.com
+GIVE_DB_DATABASE=ladill_give
+```
+
+Add `give` to `config/pdns.php` service subdomains.
+
+## 5. nginx + TLS
+
+```bash
+sudo deployment/setup-service-subdomain-nginx.sh give --app /var/www/ladill-give/current
+```
+
+## 6. First deploy
+
+```bash
+cd /var/www/ladill-give/current
+php artisan migrate --force
+php artisan config:cache route:cache view:cache
+```
+
+## 7. Verify
+
+- SSO login at `give.ladill.com`
+- Create a giving page, download QR PNG
+- Scan `/q/<code>`, give test amount, confirm wallet credit (net of 9%)
+- Withdraw from `account.ladill.com/wallet`
+
+## Product IA (blueprint)
+
+- **Overview** — total raised, donors, active causes, recent donations
+- **Giving Pages** — create/manage branded giving pages + QR
+- **Donations** — incoming donation feed
+- **Payouts** — wallet-first settlement, withdraw to bank/MoMo
+- **Settings** — organisation profile