💳 RCBC Debt Tracker

A mobile-first Progressive Web App (PWA) for tracking and managing RCBC credit card debt repayment. Built with React, TypeScript, Firebase, and Tailwind CSS.

🎨 Design Philosophy

Featuring a Liquid Glass design language with the signature RCBC Blue (#4A90A4) banking theme. The UI provides a premium, modern experience across light and dark modes with:

• Glassmorphism effects with backdrop blur and transparency
• Unified animation system - subtle, performant motion design
• Custom transparent logo integrated via Firebase Storage
• Inter typography with consistent spacing scale
• Responsive liquid glass cards with soft shadows

✨ Features

🌐 NEW: Full Offline Support

• Works Completely Offline: View data, make payments, and update debt without internet
• Automatic Sync: Changes sync automatically when connection is restored
• Visual Feedback: Real-time offline indicator with sync status
• Queue Management: Pending changes tracked with retry logic
• No Data Loss: All changes persisted locally until synced
• 📖 See OFFLINE_QUICK_START.md for user guide
• 🔧 See OFFLINE_FEATURES.md for technical docs

📊 Debt Dashboard

• Real-time Debt Tracking: Display current debt balance with large, readable typography
• Motivational Dashboard: Progress milestones (25%, 50%, 75%, 100%) with celebration animations
• Interest Savings Tracker: See how much interest you've saved by paying more than the minimum
• Debt-Free Projection: Estimated payoff date based on payment history
• Minimum Payment Calculator: Automatic calculation of required minimum payments (5% of balance or ₱500)
• Payment Logging: Easy-to-use numeric pad optimized input for recording payments
• Interest vs Principal Split: See exactly how much of your payment goes to interest vs principal reduction
• Recent Activity Feed: Real-time payment history with Firestore subscriptions

📈 Payment Simulator

• Repayment Timeline: Calculate how long it will take to pay off your debt
• Total Interest Projection: See the total interest you'll pay over the life of the debt
• Month-by-Month Schedule: Detailed payment schedule showing balance reduction over time
• Quick Amount Presets: Test different payment scenarios with one tap
• Average Daily Balance (ADB) Calculations: RCBC-accurate interest projections

📋 Payment History

• Real-time payment tracking with Firestore subscriptions
• Payment type indicators (payment vs adjustment)
• Detailed interest and principal breakdowns
• Recent activity feed (last 10 transactions)

✏️ Manual Adjustments

• Bottom-sheet drawer for easy debt principal adjustments
• Custom minimum payment settings
• Add notes for corrections or lump-sum payments
• One-click reset functionality with confirmation modal

🧮 RCBC Credit Card Interest Calculation

This app uses the RCBC-specific Average Daily Balance (ADB) method:

• Monthly Interest Rate: 3.5% (42% APR) - typical for Philippine credit cards
• Daily Interest Rate: 0.035 / 30 = 0.001166667
• Minimum Payment: 5% of outstanding balance or ₱500, whichever is higher
• Interest Method: Average Daily Balance with daily compounding
• Billing Cycle: 30 days (starts 22nd, due 17th)

Formula

Interest = Average Daily Balance × Daily Rate × Days in Cycle
Principal Payment = Total Payment - Interest
New Balance = Principal - Principal Payment

Implemented in src/utils/adbInterestCalculation.ts with full support for:

• Payment split calculations (interest-first allocation)
• Multi-month payment projections
• Daily balance tracking
• Accurate RCBC billing cycle dates

🚀 Technology Stack

• Frontend: React 19 + TypeScript
• Build Tool: Vite 7.2.4 (Fast, modern bundler with HMR)
• Styling: Tailwind CSS v3.4 + Custom Match Aesthetic Design System
• Routing: React Router DOM v7
• UI Components: shadcn/ui + Radix UI primitives
• Backend:
  • Cloud Firestore (real-time data sync with IndexedDB persistence)
  • Firebase Storage (logo and asset hosting)
  • Firebase Data Connect (GraphQL API)
• Performance:
  • 3-Layer Caching (IndexedDB + LocalStorage + Service Worker)
  • Offline-first data loading strategy
  • Code splitting with manual chunks
  • Workbox runtime caching strategies
• PWA: vite-plugin-pwa with full offline capability and auto-updates
• Offline Services:
  • IndexedDB storage with automatic queue management
  • Network status monitoring and auto-sync
  • Retry logic with exponential backoff
• State Management: React Context API (ThemeContext, AuthContext)
• Deployment: Vercel with encrypted environment variables

📱 Mobile-First Design

• Touch-Optimized: Large touch targets, swipe gestures
• Bottom Navigation: Thumb-friendly navigation bar
• Numeric Input: inputMode="decimal" for native number keyboards
• Safe Areas: Respects device notches and rounded corners
• Responsive: Works perfectly on all screen sizes

🔧 Setup & Installation

Prerequisites

• Node.js 18+
• npm or yarn
• Firebase account
• Vercel CLI (for deployment)

Local Development

1. Clone the repository

git clone https://github.com/Deign86/rcbc-debt-tracker.git
cd rcbc-debt-tracker

2. Install dependencies

npm install

3. Configure Environment Variables

• Copy .env.example to .env

cp .env.example .env

• Fill in your Firebase credentials in .env:

VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

4. Set up Firebase

• Create a Firebase project at console.firebase.google.com
• Enable the following services:
  • Authentication (Email/Password provider)
  • Cloud Firestore (Database)
  • Firebase Storage (For logos and assets)
  • Firebase Data Connect (Optional, for GraphQL API)
• Configure Storage Rules (set to test mode for development)
• Copy your Firebase config values to .env

5. Start development server

npm run dev

Visit http://localhost:5173 in your browser.

Build for Production

npm run build

Deploy to Vercel

1. Install Vercel CLI

npm i -g vercel

2. Link your project

vercel link

3. Add environment variables to Vercel

# Add each Firebase config variable
vercel env add VITE_FIREBASE_API_KEY production
vercel env add VITE_FIREBASE_AUTH_DOMAIN production
vercel env add VITE_FIREBASE_PROJECT_ID production
vercel env add VITE_FIREBASE_STORAGE_BUCKET production
vercel env add VITE_FIREBASE_MESSAGING_SENDER_ID production
vercel env add VITE_FIREBASE_APP_ID production

4. Deploy

vercel --prod

Security Note: All sensitive Firebase credentials are stored as encrypted environment variables. Never commit .env files or expose API keys in your codebase.

📂 Project Structure

rcbc-debt-tracker/
├── .github/
│   └── copilot-instructions.md  # AI coding agent instructions
├── src/
│   ├── components/              # React components
│   │   ├── Layout.tsx           # Desktop sidebar + mobile bottom nav
│   │   ├── DebtCard.tsx         # Debt display card
│   │   ├── PaymentForm.tsx      # Payment input form
│   │   ├── MotivationalDashboard.tsx # Progress milestones
│   │   ├── CelebrationAnimation.tsx  # Milestone celebrations
│   │   ├── EditDebtSheet.tsx    # Bottom sheet for debt editing
│   │   ├── EditMinPaymentSheet.tsx # Min payment editor
│   │   ├── ResetModal.tsx       # Reset confirmation modal
│   │   ├── SuccessModal.tsx     # Payment success feedback
│   │   ├── WelcomeAnimation.tsx # First-time user experience
│   │   └── ui/                  # shadcn/ui components
│   │       ├── button.tsx
│   │       ├── card.tsx
│   │       ├── glass-card.tsx   # Glassmorphism card component
│   │       ├── sheet.tsx
│   │       └── ...
│   ├── pages/                   # Route pages
│   │   ├── Dashboard.tsx        # Main dashboard with motivational stats
│   │   ├── Simulator.tsx        # Payment simulator with ADB calculations
│   │   ├── History.tsx          # Payment history (placeholder)
│   │   └── Preferences.tsx      # Theme toggle and settings
│   ├── hooks/                   # Custom React hooks
│   │   └── useDebtCalculator.ts # RCBC ADB calculation logic
│   ├── contexts/                # React Context providers
│   │   ├── ThemeContext.tsx     # Theme management (light/dark)
│   │   └── AuthContext.tsx      # Auth context (single-user mode)
│   ├── services/                # Firebase & caching services
│   │   ├── firestoreService.ts  # Firestore CRUD with cache-first strategy
│   │   ├── cacheService.ts      # LocalStorage caching layer (5min/10min TTL)
│   │   └── initializeFirestore.ts # Firestore initialization
│   ├── utils/                   # Utility functions
│   │   ├── adbInterestCalculation.ts # **Core ADB calculation logic**
│   │   ├── currency.ts          # Currency formatting
│   │   └── debtMotivation.ts    # Milestone tracking
│   ├── types/                   # TypeScript definitions
│   │   └── debt.ts              # Debt, Payment, Milestone interfaces
│   ├── config/                  # Configuration
│   │   ├── firebase.ts          # Firebase init with IndexedDB persistence
│   │   └── billingConstants.ts  # RCBC billing cycle constants
│   ├── lib/
│   │   └── utils.ts             # Tailwind merge utility (cn)
│   ├── dataconnect-generated/   # Firebase Data Connect SDK
│   └── App.tsx                  # Main app with routing
├── dataconnect/                 # GraphQL schema & queries
│   ├── dataconnect.yaml
│   ├── schema/schema.gql
│   └── example/
│       ├── queries.gql
│       └── mutations.gql
├── scripts/
│   └── upload-logos.cjs         # Firebase Storage upload script
├── public/
│   ├── manifest.json            # PWA manifest
│   └── assets/
├── .env.example                 # Environment template
├── .gitignore                   # Git ignore (includes .env files)
├── components.json              # shadcn/ui configuration
├── firebase.json                # Firebase config
├── firestore.rules              # Firestore security rules
├── storage.rules                # Firebase Storage security rules
├── tailwind.config.js           # Custom Match Aesthetic theme
├── vite.config.ts               # Vite + PWA + code splitting config
└── package.json

🔐 Security & Privacy

• Environment Variables: All Firebase credentials stored in .env files (gitignored)
• Zero Secrets in Code: Complete removal of API keys from codebase and git history
• Vercel Encryption: Production secrets encrypted in Vercel environment
• Firebase Authentication: Secure user sessions with token-based auth
• Storage Security: Firebase Storage rules configured for controlled access
• HTTPS-Only: All production traffic over secure connections
• Client-Side Calculations: Financial calculations performed locally
• No Data Sharing: User financial data never shared with third parties

Security Measures Implemented:

1. Migrated all secrets to environment variables with VITE_ prefix
2. Cleaned entire git history using git-filter-repo to remove exposed credentials
3. Added .env, .env.local, .env.production to .gitignore
4. Created .env.example template for secure onboarding
5. Configured Vercel CLI for encrypted environment variable management

📊 Roadmap

✅ Completed

• Dark mode with theme toggle and smooth transitions
• Cloud Firestore for data persistence with real-time subscriptions
• Firebase Storage for logo and assets
• Custom transparent logo with Match aesthetic
• Environment variable security implementation
• Git history cleaned of sensitive data
• Vercel deployment with encrypted secrets
• Firebase Data Connect GraphQL API setup
• Mobile-first responsive design with desktop sidebar
• RCBC-specific ADB interest calculations (core feature)
• 3-layer caching strategy (IndexedDB + LocalStorage + Service Worker)
• Motivational dashboard with milestone tracking
• Celebration animations for payment milestones
• Payment simulator with accurate projections
• PWA with offline support via vite-plugin-pwa
• Real-time activity feed with Firestore subscriptions
• Manual debt adjustments with notes
• Custom minimum payment settings
• One-click reset functionality
• shadcn/ui component library integration
• Welcome animation for first-time users
• AI coding agent instructions in .github/copilot-instructions.md
• Liquid Glass Design System - RCBC Blue (#4A90A4) theme overhaul
• Unified animation system - fade-in, scale-in, subtle pulse
• Glassmorphism UI components - glass-card, backdrop-blur effects
• Performance-optimized transitions - targeted hover states

🚧 In Progress

• Payment history page with full transaction list
• Charts and analytics visualizations

📅 Planned Features

• Multiple credit card support
• Push notifications for payment reminders
• Budget forecasting and recommendations
• Debt-free celebration animations
• Payment streak tracking
• Custom payment goals

🎨 Design System

Liquid Glass Theme

The app uses a modern Liquid Glass design system with the RCBC Blue banking palette:

Color Palette

• Primary (RCBC Blue): #4A90A4 - Trust, professionalism, banking
• Surface Glass: Semi-transparent whites with backdrop blur
• Dark Mode Glass: Dark surfaces with subtle transparency
• Accent States: Emerald green for success, amber for warnings

Animation System

Unified, performant motion design principles:

• animate-fade-in (0.3s) - Content entrance with subtle Y-translate
• animate-scale-in (0.2s) - Modals and dialogs only
• animate-pulse-subtle - Gentle emphasis, used sparingly
• Stagger delays: 50-250ms for sequential content
• Transitions: Targeted transition-colors for hover states (not transition-all)

Glassmorphism Components

• Glass Cards: glass-card class with backdrop-blur, border glow
• Glass Buttons: Translucent with soft hover states
• Background: Static gradient orbs for depth (no animation)

Typography

• Font Family: Inter (Google Fonts)
• Headings: Bold weight with proper hierarchy
• Body: Regular weight, optimized for readability
• Numeric: Tabular figures for financial data alignment

Components

• Glass Cards: Elevated surfaces with backdrop-blur and subtle borders
• Buttons: Consistent touch targets (minimum 44px height), soft hover glow
• Bottom Sheets: Native-feeling drawer interactions with scale-in animation
• Modals: Centered overlays with backdrop blur, scale-in entrance

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Never commit secrets - Use environment variables
4. Follow the existing code style - TypeScript + functional components
5. Test thoroughly - Ensure mobile responsiveness
6. Submit a Pull Request

Development Guidelines

• Use TypeScript for type safety
• Follow React best practices (hooks, functional components)
• Maintain mobile-first responsive design
• Keep Firebase security rules updated
• Document new features in README

📄 License

MIT License - feel free to use this project for personal or commercial purposes.

🙏 Acknowledgments

• Built for managing RCBC credit card debt in the Philippines
• Inspired by the need for transparent debt tracking
• RCBC interest calculation based on typical Philippine credit card terms

📧 Contact

• GitHub: @Deign86
• Project Link: https://github.com/Deign86/rcbc-debt-tracker
• Live Demo: https://rcbc-debt-tracker-hephfu9wj-deign86s-projects.vercel.app

---

Note: This is an independent project and is not officially affiliated with RCBC (Rizal Commercial Banking Corporation).