A modern React + TypeScript financial calculator suite built with TanStack Query, TanStack Router, and shadcn/ui components. Currently includes credit card interest calculator and mortgage simulator.
- Step-based Calculator: Choose bank presets, edit inputs, and review results
- Bank Presets: Built-in presets for Mexican banks (BBVA, Santander, Banorte, etc.)
- Flexible Inputs: Adjust APR, payment percentages, fees, interest methods, and more
- Payment Schedule: Detailed month-by-month breakdown with warnings for growing balances
- History Management: Save, load, and manage calculation history with localStorage
- Spanish Localization: Full Spanish language support with proper currency formatting
- Responsive Design: Two-column layout optimized for desktop and mobile
- Multiple Product Types: Supports Hipoteca Fija, Hipoteca Creciente, and other BBVA products
- Accurate Calculations: Matches the exact format and calculations from BBVA's amortization tables
- Real-time Updates: Uses TanStack Query for efficient caching and real-time calculations
- URL Persistence: All form values are saved in the URL for easy sharing
- Comprehensive Inputs: Property value, LTV, interest rates, costs, insurance, and prepayments
- Amortization Schedule: Detailed month-by-month breakdown with all payment components
- Prepayment Support: Configure additional payments with term reduction or installment reduction
- History Management: Save and manage multiple mortgage calculations
- Responsive UI: Built with shadcn/ui components for a modern, accessible interface
- Frontend: React 19 + TypeScript (strict mode)
- UI Components: shadcn/ui + Tailwind CSS
- State Management: TanStack Query for server state, React hooks for local state
- Routing: TanStack Router with file-based routing
- Forms: react-hook-form with valibot validation
- Tables: TanStack Table for payment schedules
- Storage: localStorage with valibot schema validation
- Build Tool: Vite
- Node.js 18+
- pnpm 8+
# Clone the repository
git clone <repository-url>
cd catastrofy-2
# Install dependencies
pnpm install
# Start development server
pnpm run dev:webThe app will be available at http://localhost:3001
pnpm run dev- Start all apps in development modepnpm run dev:web- Start only the web apppnpm run build- Build for productionpnpm run check-types- Run TypeScript type checking
- Credit Card Calculator: Navigate to
/(root) or/calculator - Mortgage Simulator: Navigate to
/simulators/mortgage
Select from built-in presets for Mexican banks or create custom ones. Each preset includes:
- Annual Percentage Rate (APR)
- Minimum payment percentage
- Payment floor amount
- Interest calculation method
- Payment formula type
- Principal: Starting credit card balance
- APR: Annual interest rate (0-200%)
- Daily Rate: Automatically calculated from APR (can be overridden)
- Cycle Days: Billing cycle length (28-31 typical)
- Minimum Payment: Percentage and floor amount
- Fees: Optional monthly fees
- New Charges: Optional monthly spending
- Interest Method: Choose calculation method
- Payment Formula: How minimum payment is calculated
View comprehensive results including:
- Summary Cards: Months to payoff, total paid, total interest
- Warnings: Alerts for growing balances, safety caps, interest-only payments
- Payment Schedule: Detailed monthly breakdown with sorting and pagination
- Calculation Details: All input parameters used
- Auto-save: Calculations are automatically saved to localStorage
- History Panel: Browse, search, and manage saved calculations
- Export/Import: All data is stored locally and can be managed
Navigate to /simulators/mortgage to access the mortgage simulator.
Configure the fundamental mortgage parameters:
- Product Type: Choose from Hipoteca Fija, Hipoteca Creciente, or other BBVA products
- Property Value: Total value of the property in MXN
- LTV (Loan-to-Value): Percentage of property value to finance (typically 80-90%)
- Principal: Loan amount (auto-calculated from property value × LTV)
- Term: Loan duration in months (60-240 typical)
- Interest Rate: Annual interest rate with support for rate bands
Set up all associated costs:
- Opening Commission: One-time fee as percentage of principal
- Admin Commission: Monthly deferred commission on original principal
- Appraisal Cost: Property appraisal fee
- Notary Cost: Legal documentation costs
- Pre-origination Cost: Additional upfront costs
Configure insurance requirements:
- Life Insurance: Annual rate on outstanding balance
- Hazard Insurance: Annual rate on insured property value
- Insured Value Factor: Portion of property to insure (typically 80-100%)
- Reindexing: Annual adjustment rate for insured value
Set up additional payments:
- Prepayment Amount: Additional payment amount
- Prepayment Month: When to apply the prepayment
- Prepayment Mode:
- Reduce Term: Keep same payment, reduce loan duration
- Reduce Installment: Keep same term, reduce monthly payment
View comprehensive results including:
- Summary Totals: Total interest, principal, insurance, and grand total
- Pago por Mil: Payment per thousand pesos borrowed
- Initial Disbursement: Total upfront costs required
- Amortization Schedule: Month-by-month breakdown showing:
- Opening/closing balances
- Interest and principal components
- Insurance and commission costs
- Total monthly payment
- Prepayment amounts (if any)
- Save Calculations: Automatically save mortgage scenarios
- Load Previous: Access and modify previous calculations
- Compare Scenarios: Switch between different mortgage configurations
/lib/types.ts: TypeScript interfaces and types/lib/schemas.ts: Valibot validation schemas/lib/calculator.ts: Pure calculation functions/lib/presets/: Bank preset definitions/services/: Data layer for calculations and presets/hooks/: TanStack Query hooks for data management/components/: React components for UI
/lib/types/mortgage.ts: Mortgage-specific TypeScript types/lib/schemas/mortgageSchema.ts: Valibot validation for mortgage inputs/lib/mortgageMath.ts: Pure mortgage calculation functions/hooks/useMortgageCalculations.ts: TanStack Query hooks for mortgage data/components/mortgage-*: Mortgage-specific UI components/routes/simulators/mortgage.tsx: Main mortgage simulator page
CalculatorForm: Main input form with validationCalculationResults: Results display with summary and schedulePaymentScheduleTable: TanStack Table for payment breakdownCalculationHistory: Side panel for managing saved calculations
MortgageForm: Multi-step form for mortgage configurationMortgageResults: Comprehensive results display with amortization schedulePaymentScheduleTable: Detailed mortgage payment breakdownMortgageHistory: Side panel for managing saved mortgage calculations
- User selects preset and configures inputs
- Form validates data using valibot schemas
- Calculator functions compute payment schedule
- Results are displayed and saved to localStorage
- TanStack Query manages cache and updates
- User configures mortgage parameters through multi-step form
- Form validates data using mortgage-specific valibot schemas
- Mortgage calculation functions compute amortization schedule
- Results are displayed with comprehensive breakdown
- Calculations are saved to localStorage with history management
- TanStack Query handles caching and real-time updates
- ✅ Credit Card Interest Calculator (fully functional)
- ✅ Mortgage Simulator Core (fully functional)
- ✅ Bank Presets for Mexican institutions
- ✅ History Management for both calculators
- ✅ Responsive UI with dark/light mode
- ✅ Spanish localization
- ✅ URL persistence for mortgage simulator
- Disabled Test Files: Several test files are currently disabled:
apps/web/src/lib/__tests__/calculator.test.ts.disabled- Credit card calculator testsapps/web/src/routes/simulators/mortgage-test.tsx.disabled- Mortgage simulator test page
- Test Coverage: No active test suite is currently running
- Integration Tests: Missing end-to-end tests for both calculators
- Preset Management: No built-in mortgage presets (unlike credit card calculator)
- Export Functionality: No PDF or Excel export for amortization schedules
- Comparison Tools: No side-by-side comparison of different mortgage scenarios
- Advanced Features:
- Variable rate adjustments
- Balloon payments
- Interest-only periods
- Bi-weekly payment options
- Additional Banks: Limited preset coverage for Mexican banks
- International Support: No support for other countries' banking systems
- Advanced Scenarios: No support for promotional rates or balance transfers
- Data Export/Import: No bulk data management capabilities
- User Accounts: No cloud storage or user authentication
- Mobile App: No native mobile application
- API Integration: No real-time rate updates from financial institutions
- Testing: Re-enable and expand test coverage
- Mortgage Presets: Add bank-specific mortgage product presets
- Export Features: Implement PDF/Excel export functionality
- Comparison Tools: Add scenario comparison capabilities
- Mobile Optimization: Enhance mobile user experience
- API Integration: Connect to real-time financial data sources
All inputs are validated using valibot schemas with:
- Type Safety: Strict TypeScript with no
anytypes - Bounds Checking: APR (0-200%), payment percentages (0-50%), etc.
- Data Coercion: Automatic conversion from strings to numbers
- Storage Validation: localStorage payloads validated on read/write
The app supports Spanish (es-MX) by default with:
- Labels: All UI text in Spanish
- Currency: Mexican Peso (MXN) formatting
- Numbers: Locale-specific number and percentage formatting
- Dates: Relative time display in Spanish
- Fork the repository
- Create a feature branch
- Make changes with proper TypeScript types
- Add tests for new functionality
- Submit a pull request
This project is licensed under the MIT License.
- Built with TanStack libraries
- UI components from shadcn/ui
- Validation powered by Valibot
- Icons from Lucide React