Fynla - UK Financial Planning System

A comprehensive financial planning web application designed for UK individuals and families, covering seven integrated modules: Protection, Savings, Investment, Retirement, Estate Planning, Goals & Life Events, and Coordination. Features an AI-powered chat assistant (Fyn), unified financial plans with PDF export, a complete design system, a mobile web pathway (/m), and a native SwiftUI iOS client on TestFlight.

GOLDEN RULE #20 (CSJ, NEVER IGNORE): every Fyn change — prompt, vocabulary, behaviour, rendering — is made ONCE, in ONE place, for ALL surfaces and paths. If more than one mechanism implements the behaviour, consolidating to one source is PART of the fix. Full text: CLAUDE.md Rule 20.

• Overview
• Current Status
• Core Features
• Module Features
• Technology Stack
• Installation
• Development
• Testing
• Deployment
• Documentation
• Recent Updates

Fynla is a UK-focused comprehensive financial planning application that helps individuals and families:

• Analyze their current financial situation across all major areas
• Identify gaps, risks, and opportunities
• Plan for their financial future with confidence
• Track progress towards financial goals
• Generate professional reports and recommendations

Three clients, one Laravel backend. Backend changes reach all three; each front end is built and verified separately.

Version: v1.0 Status: Production (https://fynla.org) Last Updated: 20 August 2026

main is what runs on fynla.org and dev is what runs on csjones.co/fynla. dev currently carries substantial work not yet released to production.

The iOS paywall shows "Premium subscriptions are unavailable. Please try again later." because no in-app purchase products exist in App Store Connect. Verified 2026-08-17 against the ASC API — both app records return zero:

This is configuration, not code. StoreKit returns nothing, and the guard at ios-native/.../SubscriptionModel.swift:291 requires the returned set to equal StoreProductIdentifier.all exactly, so the paywall reports unavailable.

To resolve, create in App Store Connect (product IDs must match ios-native/StoreKit/Fynla.storekit and StoreKitModels.swift:4-5):

org.fynla.premium.monthly   £6.99    P1M
org.fynla.premium.annual    £59.99   P1Y

No second Apple Developer account is needed — the existing membership covers this. In-app purchases do require the Paid Applications Agreement to be Active (App Store Connect → Business): accept the agreement, add banking details and complete tax forms. Until it is Active, App Store Connect will not allow in-app purchases to be created.

Web and /m are unaffected: /m hands off to the web app for payment (issueWebHandoff('subscription')), which is the agreed architecture. Native cannot use that route because Apple requires in-app purchase for digital goods.

Full analysis: August/August17Updates/iOSBugs/BUG-01-subscription-upgrade.md.

• Email Verification: 6-digit code verification for registration and login
• TOTP Multi-Factor Authentication: QR code setup, recovery codes, verification modal
• Failed Login Tracking: Progressive lockout (1min - 5min - 30min - 24hr)
• Session Management: View active sessions, revoke from Security Settings
• GDPR Compliance: Data export (JSON/CSV), data erasure, consent tracking
• Audit Logging: Auditable trait applied across the financial models
• RBAC: Role-based access (User, Support, Admin) with granular permissions
• Secure Authentication: Laravel Sanctum token-based API authentication
• Rate Limiting: 300 requests/minute for API, 5/minute for auth endpoints
• Preview Mode: Try the app without registration

• User Profiles: Comprehensive personal and financial information
• Spouse Accounts: Auto-creation and linking with bidirectional access
• Joint Ownership: Support for jointly owned assets (properties, investments, savings)
• Trust Ownership: Track assets held in trust
• Data Sharing: Granular permissions for spouse data access
• Family Members: Track dependents with relationship types

The main dashboard provides a unified view of your financial planning:

• Net Worth Overview: Real-time tracking of assets and liabilities
• Wealth Summary: Side-by-side household breakdown with spouse data
• Estate Planning Summary: IHT liability and probate readiness
• Protection Overview: Coverage status and policy summary
• Plans Card: Quick access to all planning modules

Fyn is one chat surface with two write states behind it. The user never sees or feels the switch.

• Onboarding Fyn runs the bubble-driven onboarding flow and is the only state that enters or edits data
• Advice Fyn is read-only — it answers questions using the recommendation engine, the risk module and every other engine, and exposes no record-creating tools at all
• Write intents raised mid-conversation are delegated to the capture path internally, so "add my pension" is captured without the user leaving the conversation or seeing a mode change
• One prompt, one endpoint — both states send the same system prompt plus per-turn context, and all three clients post to the same chat endpoint, so read/write dispatch is decided server-side rather than by any front end
• CoALA memory — semantic, episodic and procedural memory, with write-safety enforced at the dispatch boundary and audited

• Database-Driven: All UK tax values stored in database (never hardcoded)
• Multi-Year Support: Tax years 2021/22 through 2027/28 (active: 2026/27)
• Admin Panel: Easy tax year switching and value updates
• Comprehensive Coverage: Income tax, NI, CGT, dividend tax, IHT, stamp duty, ISA/pension allowances

Upload financial documents and let AI extract the data automatically:

• Supported Formats: PDF, PNG, JPG, JPEG, WebP, Excel (XLSX, XLS), CSV
• AI-Powered: Uses Anthropic Claude for intelligent data extraction
• Document Types: Pension statements, insurance policies, investment statements, mortgage/savings statements
• Review & Confirm: Review extracted data with confidence scores before saving

Emergency instructions document for surviving spouse:

• 4-Part Guide: Immediate actions, account access, long-term plans, funeral wishes
• Auto-Population: Automatically aggregates data from all modules
• Dual View: Each spouse can edit their own and view partner's (read-only)

Try the full application with realistic financial data:

Purpose: Analyze life insurance, critical illness, and income protection coverage

Features:

• Policy portfolio view with filtering and sorting
• Coverage gap analysis comparing recommended vs. current
• Coverage adequacy analysis based on 8 metrics
• Human capital calculation (lifetime earning potential)
• Premium affordability analysis
• Strategy tab with prioritized recommendations
• Professional report generation

Policy Types Supported:

• Life Insurance (Decreasing Term, Level Term, Whole of Life, Family Income Benefit)
• Critical Illness
• Income Protection
• Disability
• Sickness & Illness

Purpose: Emergency fund analysis and savings goal tracking

Features:

• Emergency fund calculator (3-6 month runway)
• ISA allowance monitoring (£20,000 limit, cross-module)
• Liquidity ladder (immediate, notice, fixed)
• Savings goals with progress tracking
• Interest rate analysis

Purpose: Portfolio tracking with optimization and goal-based planning

Features:

• Portfolio overview with holdings management
• Asset allocation visualization
• Account types: ISA, GIA, NS&I, Bonds, VCT, EIS
• Rebalancing recommendations
• Fee analysis (platform fees, fund OCFs, advisor fees)
• Tax efficiency analysis
• Annualized return calculations (gross and net of fees)
• Portfolio strategy recommendations

Purpose: Pension tracking, projection, and decumulation planning

Features:

• Pension inventory (DC, DB, State pensions)
• DC pension portfolio optimization with holdings management
• Advanced risk analytics (Alpha, Beta, Sharpe Ratio)
• Monte Carlo projections with scenario modeling
• Income projection with stacked area charts
• Annual allowance tracking (£60,000 + 3-year carry forward)
• Contribution optimization with tax relief calculations
• Retirement income planning with tax calculations
• Strategy recommendations

Purpose: IHT calculation, net worth tracking, and estate strategy

Features:

• IHT calculations (single and married scenarios)
• Net worth tracking with comprehensive asset/liability breakdown
• Gifting strategy (PET and CLT with 7-year taper relief)
• Trust management with beneficiary details
• Will planning with executor details
• Actuarial projections (life expectancy-based)
• Second death analysis with combined allowances
• Life policy strategy comparison
• Probate readiness assessment
• Chattels & valuables tracking with CGT calculator
• Business interests with Business Relief assessment

IHT Allowances:

• Nil Rate Band: £325,000
• Residence Nil Rate Band: £175,000
• Married couples: Combined £650,000 NRB + £350,000 RNRB

Purpose: Financial goal tracking with projections and life event planning

Features:

• Centralised goal management with automatic module assignment
• 8 goal types: Emergency fund, property, education, retirement, wealth, wedding, holiday, custom
• Visual progress bars and milestone tracker (25/50/75/100%)
• Contribution streak tracking with badges
• Life event management (income/expense impacts)
• Net worth projection chart using Future Value calculations
• Cash flow view with income, expenditure, and surplus
• Household view toggle for joint goals
• Dashboard integration with projection chart

┌─────────────────────────────────────┐
│ Presentation Layer                  │
│ Web SPA · Mobile /m · Native iOS    │
│ Vue 3 + Vuex · SwiftUI              │
└─────────────────┬───────────────────┘
                  │ REST API (shared by all clients)
                  ↓
┌─────────────────────────────────────┐
│ Application Layer                   │
│ Controllers → Agents → Services     │
│ Fyn AI Chat + Document Extraction   │
└─────────────────┬───────────────────┘
                  │ Eloquent ORM
                  ↓
┌─────────────────────────────────────┐
│ Data Layer                          │
│ MySQL 8.0+                          │
│ Memcached (calculation caching)     │
└─────────────────────────────────────┘

Each module has an intelligent agent that orchestrates analysis:

• PHP: 8.2 or higher
• MySQL: 8.0 or higher
• Node.js: 18.x or higher
• Composer: 2.5 or higher
• RAM: 4GB minimum, 8GB recommended

# Clone repository
git clone <repository-url> fynla
cd fynla

# Install dependencies
composer install
npm install

# Environment setup
cp .env.example .env
php artisan key:generate

# Configure database in .env, then:
php artisan migrate

# Seed required data (tax config, reference data, preview personas, admin user)
php artisan db:seed

# Start development servers
./dev.sh

Recommended: Use the startup script that handles everything:

./dev.sh

This script:

• Kills existing server processes
• Exports correct environment variables
• Clears Laravel and Vite caches
• Verifies MySQL connection
• Starts both Laravel (port 8000) and Vite (port 5173)

Manual Alternative (3 terminals):

# Terminal 1 - Laravel Backend
php artisan serve

# Terminal 2 - Vite Frontend
npm run dev

# Terminal 3 - Queue Worker (optional)
php artisan queue:work database

# Format code (PSR-12)
./vendor/bin/pint

# Check without fixing
./vendor/bin/pint --test

# Run all tests
./vendor/bin/pest

# Run with increased memory (recommended)
php -d memory_limit=512M ./vendor/bin/pest

# Run specific suite
./vendor/bin/pest --testsuite=Unit
./vendor/bin/pest --testsuite=Feature
./vendor/bin/pest --testsuite=Architecture

# Run specific file
./vendor/bin/pest tests/Feature/Protection/ProtectionApiTest.php

Six suites are declared in phpunit.xml:

tests/Browser/scenarios/BS-NN-*.php carries the acceptance contract for end-to-end work — the docblock at the top of each scenario is what "done" means for it. A green unit suite does not satisfy a browser scenario.

Conventions live in tests/CLAUDE.md.

Tests may truncate database tables. Reseed required data:

php artisan db:seed --class=TaxConfigurationSeeder --force
php artisan db:seed --class=PreviewUserSeeder --force

Use the deployment-specific build scripts:

# For fynla.org (root deployment)
./deploy/fynla-org/build.sh

# For csjones.co/fynla (subdirectory deployment)
./deploy/csjones-fynla/build.sh

• PHP 8.2+ with extensions: BCMath, Ctype, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML
• MySQL 8.0+
• Nginx or Apache with mod_rewrite
• SSL Certificate

php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear

• Native SwiftUI iOS client — all seven build packages merged (PRs #630–#637), bringing dashboard, financial data, projections and achievements to parity with /m; shipped to TestFlight (build 6, 12 August) against the staging backend. Testers must register on csjones.co/fynla, not fynla.org — the TestFlight build reads the staging database
• Golden Rule #20 — one Fyn, one place — parallel mechanisms doing the same job (two ownership vocabularies, two answer paths, per-surface markdown renderers) consolidated into single shared sources, so a Fyn fix lands once and reaches web, /m and native together
• Fyn capture and advice routing — advice-to-capture handoff, charitable giving, expenditure gating, household facts and in-answer view links reworked across PRs #695–#706
• Marketing pipeline — Google Drive service-account ingest, AI-assisted copy, video processing and scheduled social posting (PRs #690–#694)
• Estate bequests — bequest management on the web, with a mobile /m screen that hands off to the web app for edits (PR #711)
• Spouse-link integrity — deleted-spouse cleanup, a duplicate spouse-email guard, and the widow persona retired from the preview set (PRs #695, #697, #708–#710)

• Production Launch — Fynla v1.0 live at https://fynla.org, with csjones.co/fynla as the dev/staging environment and a formalised feature → dev → main release workflow
• Freemium Tiers & Payments — Tier-based freemium model with Revolut subscription payments, tier-driven upgrade flows, and the public pricing page rebuilt around tiers
• Fyn AI Unified Architecture — One unified system prompt across both Fyn states (onboarding capture and read-only advice), with write intents routed through an unseen capture handoff; CoALA memory programme (semantic, episodic, and procedural memory) landed via PR #550 (2026-06-13), with the shared FynLoop + GroundGate substrate underneath both Fyn states, since released to production
• Save-Tax Campaign & Tax Strategy — Public save-tax funnel feeding a Fyn-led onboarding journey; tax strategy catalogue joins the recommendation aggregator as a seventh module with a TaxOptimisationAgent, composed household tax plans, and dedicated Tax Strategy pages on web and mobile
• Mobile /m Pathway — Phones route to /m, which serves the mobile web build (iframed funnel plus a dedicated mobile SPA at /m/app with its own dashboard)
• Gamification Engine — Append-only points ledger with named levels, level wheel and progress on the mobile dashboard, and a gamified web dashboard
• Lifecycle Email Engine — Transactional and lifecycle email campaigns built on a master layout with reusable modules, including account-deletion lifecycle emails

• Resource Pages Redesign — Comprehensive redesign of all public resource pages: features (harvey balls comparison), FAQ (centralised data, category filters), security, glossary, our approach, one platform, financial companion, getting started. New advisors page and contact form with backend controller
• Guides & Explainers — Learning Centre replaced with categorised guide hub (Key Terms, Decision Support, Personal Journey Guides, Tax & Allowances). GuideNav and GuideArticleFooter shared components across 22 article pages
• Feature Gating — Tier-based access control: greyed sidebar items with upgrade tooltips for lower tiers, backend middleware enforcement, 10 automated tests
• Journey Links — Stage page CTAs pass life stage to registration, auto-select on onboarding. Security fix resets all Vuex stores and clears tokens on register/login
• Dashboard Improvements — Investment bar charts, empty state CTAs, Fyn chat toggle, ModuleStatusBar three-column redesign, net worth donut tooltips, matched card heights
• Site-Wide — Sentence case, in-place demo modal, Google Analytics in head, SEO structured data, sitemap with 60+ URLs, comparison page slug redirects, CSP updated for GA

• Decision Engine Upgrade (v0.9.0) — 107 DB-driven recommendation triggers across 5 modules, data readiness gates, 9-phase investment pipeline
• AI Form Fill — xAI/Grok-powered form auto-fill deployed across 14 modules, tested on production
• Full Code Review Remediation — 94 issues fixed (tax compliance, security, design system, dead code)
• Admin Tax Configuration — 568 TaxConfigService values editable across 10 tabs
• Power of Attorney — Guided creation wizard, compliance checking, print/registration tracking
• Subscription & Payments — Revolut checkout, upgrade with proration, subscription management
• Website Redesign — Journey pages, calculators sidebar, mega menu, preview personas, pricing page

• Financial Plans System (Complete Rebuild) — Unified plan framework with 5 plan types (Investment, Protection, Retirement, Estate, Goal) following a consistent 6-section structure: executive summary, current situation, toggleable actions, what-if scenarios, dynamic conclusion, PDF export
• Holistic Plan Rewrite — Frontend-orchestrated aggregation of individual module plans with priority allocation against shared disposable income
• AI Chat Assistant — AI-powered chat assistant ("Fynla Assistant") with 17 tools, SSE streaming, and simulated AI for preview personas (zero API cost for demos)
• Side Navigation Menu — Collapsible left-side navigation with expanded/collapsed modes, mobile overlay, and persisted state
• Student Preview Persona — 7th persona (Janice Taylor, 21, university student) with optimised student dashboard
• Design System Overhaul (v1.2.0) — Complete visual rebrand: Raspberry CTAs, Horizon text, Spring success, Violet warnings, Eggshell backgrounds, Segoe UI typography
• CSS Centralisation — Eliminated 1,110 lines of duplicated CSS across 65 components, established CSS governance rules
• Plan Enhancements — Structured executive summaries, personal information sections, per-account/pension recommendations with reactive charts, admin-configurable plan values (PlanConfigService)
• Code Audit — Fixed 3 critical bugs, 7 important fixes, 12 simplifications across all plan services
• Print/Save PDF — Multi-plan print support with type-specific builders and cascading line charts

• Security hardening (4 phases): data encryption at rest, brute force protection, account enumeration prevention, challenge token authentication
• Security headers: CSP hardened, permissions policy, session security, source maps disabled
• Model and API hardening: hidden attributes, mass assignment protection, generic error messages
• Revolut payment integration with subscription management
• Token storage migrated to sessionStorage exclusively

• Laravel best practices audit: 12 Form Requests, 10 API Resources, IHTController extraction
• Goals projections rewritten with simple FV calculation
• Retirement planner: income tax slider, decumulation graph, DB/State pension fallback
• Wealth summary improvements, 500 error fixes across 8 API Resources

• TOTP MFA, failed login tracking, session management, GDPR compliance, audit logging, RBAC
• Goals-based planning module with 8 goal types
• Automated risk profile calculator, financial statements
• Young Adult Saver and Retired Couple personas, 134 new security tests

This project is proprietary software. All rights reserved.

Disclaimer: This system is for demonstration and analysis purposes only, not regulated financial advice.

• Documentation: See CLAUDE.md and update folders
• Issues: Create an issue in the repository

Version: v1.0 | Last Updated: 12 June 2026 | Status: Production (https://fynla.org)

Built with Claude Code

Co-Authored-By: Claude [email protected]