CostusWorx Retirement Decision Engine Go-Live Playbook Version 2.0 · 27 May 2026 Confidential - CostusWorx Internal Use Only retireuk.costusworx.co.za # 1. Project Status Snapshot As of 27 May 2026, the UK edition of CostusWorx is deployed at retireuk.costusworx.co.za. The current production version is 2026.05.27.1. # 2. Phases Completed All phases through Phase 0c (UK fork) are shipped to production. ## 2.1 Phase 0c Highlights - UK Fork (v2026.05.27.1) Phase 0c is the complete SA-to-UK migration. Key changes: - UK asset domain classes: SippAsset, IsaAsset, WorkplacePensionAsset, StatePensionAsset - HmrcTaxCalculator with 2024/25 brackets including PA taper (60% effective rate GBP 100k-GBP 125,140) - State Pension as income stream: GBP 11,502.40/yr (35 NI qualifying years, 2024/25 rate) - Stripe billing replaces PayFast; webhook Stripe-Signature verification - UK GDPR replacing POPI; ni_number_enc encrypted field; 6-year audit retention (FCA) - SEDOL replacing JSE code; COALESCE(sedol, jse_code) backward-compat read pattern - GBP/en-GB throughout; price_gbp column with COALESCE(price_gbp, price_zar, 0) fallback - UK market data: FTSE All-Share, UK Gilts, SONIA, ONS CPI (2000-2024, 25 years) - IA sectors replacing ASISA categories - FCA COBS suitability disclosure replacing FAIS disclaimer on all reports # 3. Architecture Overview CostusWorx UK is a PHP 8.5 MVC application on standard cPanel shared hosting. It is intentionally dependency-light - no Composer at runtime, no Node, no Docker. ## 3.1 Stack ## 3.2 Key Files ## 3.3 Environment Variables (set in .htaccess via SetEnv) # 4. Gap Register The table below tracks all known gaps, their priority, and current status. # 5. Pre-Launch Checklist Use this checklist before promoting any release to production. All items must be checked before upload. ## 5.1 Code and Version - config/version.php bumped to new version string (YYYY.MM.DD.N) - public/assets/js/app.js APP_JS_VERSION updated to match - DEPLOY_NOW.md written with full file list and smoke tests for this release - No debug output, var_dump, or error_reporting(E_ALL) calls in production code - LIMIT / OFFSET values sanitised to int and inlined (PDO cannot bind LIMIT) ## 5.2 Security - All PDO queries use prepared statements with ATTR_EMULATE_PREPARES = false - Every new route protected by TenantMiddleware (or explicitly exempted for /admin/*) - All new form inputs sanitised at entry; HTML outputs escaped with htmlspecialchars(ENT_QUOTES|ENT_HTML5) - No PII or financial data in URLs or query strings - UK GDPR consent enforced before any client save (ukgdpr_consent = 1) - Sensitive actions covered by audit log (retained 6 years per FCA COBS) - Stripe webhook Stripe-Signature header verified before processing any webhook event - .htaccess does not contain live secrets committed to git ## 5.3 Performance - Single simulation completes in <3s on shared cPanel (500 runs x 25 years x 12 months) - Fund search returns in <300ms - Dashboard initial load <1s ## 5.4 UK-Specific Compliance - HMRC tax brackets verified against current Spring Budget rates - UK State Pension weekly rate current (uprated each April) - FCA COBS disclosure text present on PDF page 4 - SIPP minimum access age set to 57 (from 2028) in SippAsset::MIN_ACCESS_AGE - Lump Sum Allowance (GBP 268,275) documented in adviser-facing notes # 6. Deployment Runbook CostusWorx deploys via cPanel File Manager. There is no CI pipeline yet. ## Step 1 - Prepare Locally - Run the full pre-launch checklist (Section 5) - Write DEPLOY_NOW.md with the exact file list for this release - Bump version in BOTH config/version.php AND public/assets/js/app.js ## Step 2 - Database Migrations - Log in to cPanel -> phpMyAdmin - Run any new SQL files listed in DEPLOY_NOW.md, in order - Verify with SHOW COLUMNS or a quick SELECT before proceeding - Every migration must include a -- ROLLBACK block for reversal ## Step 3 - Upload PHP Files - cPanel File Manager -> navigate to document root - Upload changed files - confirm file permissions: PHP 644, directories 755 - Do NOT upload config/database.php, config/billing.php, or .htaccess from local git ## Step 4 - Smoke Test - Hard-refresh browser (Ctrl+F5) - footer version banner must match new APP_JS_VERSION - Log in as admin - confirm version string in footer - Create test client (with UK GDPR consent) and scenario - run simulation - confirm success rate appears in GBP - Open PDF report - confirm FCA COBS disclosure on page 4 - Check cPanel error log for PHP errors ## Step 5 - Rollback Plan - Identify what changed (DEPLOY_NOW.md lists exact paths) - If files-only: re-upload previous version's files from local git. Releases tagged YYYY.MM.DD.N in git. - If DB schema changed: run the -- ROLLBACK block from DEPLOY_NOW.md in phpMyAdmin - If state was corrupted: restore yesterday's DB snapshot via phpMyAdmin import - Run smoke tests for the previous version to confirm restore # 7. Scheduled Jobs (cPanel Cron) # 8. UK Regulatory Calendar These events require manual action by the CostusWorx administrator each year. retireuk.costusworx.co.za · Confidential · v2.0 · 27 May 2026 | Dimension | Current State | | --- | --- | | Production URL | https://retireuk.costusworx.co.za | | Current version | 2026.05.27.1 (UK fork, shipped 27 May 2026) | | Hosting | cPanel shared hosting - PHP 8.5 / MySQL 8 / UK datacentre | | Deployment method | Manual upload via cPanel File Manager | | Auth | Session-based, bcrypt passwords, HttpOnly+Secure cookies | | Multi-tenancy | tenant_id on every table; session-resolved | | Billing | Stripe (SCA-compliant) - Starter / Professional / Enterprise tiers | | Fund library | UK fund universe - FTSE ETFs, OEICs; ISIN/SEDOL identifiers | | Simulation engine | Monte Carlo 500 runs x 25 years x 12 months/year | | PDF reports | Client-side jsPDF + html2canvas; server-side mPDF (optional) | | Compliance | UK GDPR consent required; FCA COBS disclosure on all reports | | Tax engine | HmrcTaxCalculator - 2024/25 HMRC brackets with PA taper | | Asset types | SIPP, ISA, Workplace Pension, State Pension, Cash, Unit Trust | | Phase | Name | Shipped | Status | | --- | --- | --- | --- | | 0 | Foundation - auth, tenancy, basic CRUD, MC engine v1 | 2026-05-06 | Done | | 0b | Engine audit & realism fixes (sequence-of-returns, monthly cashflow, HMRC PIT in-loop, shortfall failure) | 2026-05-07 | Done | | 1 | PDF report rewrite - chart embed, full data, client-side download | 2026-05-08 | Done | | 1b | Fund PDF ingestion pipeline - upload, scan, auto-match, manual match, admin UI | 2026-05-18 | Done | | 0c | UK fork - SIPP/ISA/State Pension, HMRC tax, Stripe, UK GDPR, SEDOL, GBP, IA sectors | 2026-05-27 | Done | | 2 | Strategy comparator (top-performer query, side-by-side UI) | Target 2026-06-20 | In progress | | 3 | UK extended assets (LISA, DB pension income, annuity income, offshore bond, VCT) | Target 2026-07-05 | | | 4 | Retirement date + accumulation phase (pre-retirement contributions) | Target 2026-07-20 | | | 5 | SIPP/ISA limits, Lump Sum Allowance (GBP 268,275), NI qualifying years | Target 2026-08-05 | | | 6 | TER drag, parametric returns, correlation lock, sequence chart | Target 2026-09-05 | | | Layer | Technology | | --- | --- | | Language | PHP 8.5 with strict types, readonly properties, native enums | | Database | MySQL 8 via PDO native prepared statements (ATTR_EMULATE_PREPARES = false) | | Autoloading | Custom PSR-4 autoloader (App\ -> app/) - no Composer at runtime | | Frontend | Vanilla JS + Chart.js (CDN) + jsPDF + html2canvas (CDN) | | PDF (server-side) | mPDF (drop-in, not required - see INSTALL_MPDF.md) | | Billing | Stripe (UK SCA / card / Direct Debit) with webhook signature verification | | Hosting | cPanel shared hosting - Linux / Apache / PHP-FPM - UK datacentre | | Cron | cPanel cron for scheduled fund ingest (no background workers) | | Locale | en-GB throughout; GBP (pound sterling) symbol | | Purpose | File | | --- | --- | | Front controller / bootstrap | public/index.php | | Router | app/Http/Router.php | | Monte Carlo engine | app/Simulation/MonteCarloRunner.php | | HMRC tax calculator | app/Tax/HmrcTaxCalculator.php | | SIPP asset domain | app/Domain/Asset/SippAsset.php | | ISA asset domain | app/Domain/Asset/IsaAsset.php | | State Pension asset | app/Domain/Asset/StatePensionAsset.php | | Stripe billing | app/Billing/StripeBilling.php | | PDF report generator | app/Reporting/PdfReport.php | | SVG chart helper | app/Reporting/SvgChart.php | | OpenFIGI client | app/Integration/OpenFigiClient.php | | Dashboard JS | public/assets/js/app.js | | Layout view | public/views/_layout.php | | Variable | Purpose | | --- | --- | | STRIPE_SECRET_KEY | Stripe secret key for payment processing | | STRIPE_WEBHOOK_SECRET | Stripe webhook signing secret for /billing/notify | | ENCRYPT_KEY | AES-256-GCM key for PII encryption (base64, 32 bytes) - UK GDPR Art.32 | | OPENFIGI_API_KEY | OpenFIGI API key for UK fund metadata lookups (ISIN -> SEDOL) | | APP_ENV | production | development | | APP_DEBUG | true to enable error traces - NEVER on production | | ID | Gap | Priority | Status | | --- | --- | --- | --- | | G-01 | Strategy comparator (top-performer query, side-by-side UI) | High | Phase 2 - 2026-06-20 | | G-02 | Extended UK asset types (LISA, DB pension income, annuity income, offshore bond, VCT) | High | Phase 3 - 2026-07-05 | | G-03 | Retirement date + accumulation phase (pre-retirement contributions) | High | Phase 4 - 2026-07-20 | | G-04 | SIPP/ISA annual limits, Lump Sum Allowance (GBP 268,275) guard, NI qualifying year gap analysis | Medium | Phase 5 - 2026-08-05 | | G-05 | TER drag per asset, parametric forward-looking returns, sequence-of-returns chart | Medium | Phase 6 - 2026-09-05 | | G-06 | HMRC tax bracket admin UI (per tax year, per Spring Budget) | Low | Backlog | | G-07 | CSV export gated by subscription tier | Low | Partial - quota gate needed | | G-08 | Automated deployment pipeline (currently manual cPanel upload) | Low | Backlog | | G-09 | Stripe webhook event replay / end-to-end audit | Medium | Backlog | | G-10 | NI record lookup integration (GOV.UK API when available) | Low | Future | | Schedule | Command | Purpose | | --- | --- | --- | | 1st of month, 02:00 UTC | php bin/funds-sync.php --source lse-etf | Monthly UK ETF fund data refresh from LSE | | Daily, 03:00 UTC | cPanel automated backup | DB snapshot retained 7 days on host, weekly to OneDrive | | Manual (annually, January) | Admin -> Market Data -> Import CSV | ONS CPI / FTSE / SONIA annual data update | | Manual (annually, April) | UPDATE state_pension_rates in phpMyAdmin | State Pension weekly rate uprated each April | | Manual (within 7 days of Spring Budget) | Run uk_tax_YYYY.sql in phpMyAdmin | HMRC bracket update after Spring Budget (typically March) | | Event | Timing | Action required | | --- | --- | --- | | Spring Budget (HMRC) | Typically March | Update tax_brackets table within 7 days. Run uk_tax_YYYY.sql. | | State Pension uprating | 6 April each year | Update state_pension_rates with new weekly rate (triple-lock). | | ONS CPI / FTSE annual data | January (calendar year end) | Import CSV via Admin -> Market Data -> Import CSV. | | ISA annual allowance | 6 April each year | Confirm GBP 20,000 limit unchanged; update if HMRC changes it. | | FCA COBS suitability review | Ongoing | Monitor FCA policy statements for changes to suitability obligations. | | UK GDPR annual review | Annually | Review with DPO/compliance officer. Update retention schedules if needed. |