Introduction to SafeSpend

What is SafeSpend?

SafeSpend is a Progressive Web App (PWA) built to make weekly financial management simple and intuitive. Unlike complicated spreadsheet-based tools, SafeSpend focuses on one week at a time — encouraging healthier spending habits through short, achievable cycles.

Purpose of the App

Most personal finance apps overwhelm users with monthly reports and overwhelming category structures. SafeSpend was built to solve this by:

• Keeping financial tracking simple and visual
• Encouraging weekly budget discipline instead of monthly overload
• Providing smart, AI-powered insights in plain language
• Offering offline support so you can log expenses anywhere
• Including a Mobile Money Wallet for seamless transactions

Who is it For?

Key Benefits

User Registration & Login

SafeSpend offers two ways to get started — a full account via Google Sign-In (recommended), or a quick Guest Mode for immediate use on a single device.

2.1   Signing Up with Google (Recommended)

Google Sign-In automatically sets up your profile, syncs data across devices, and unlocks the full feature set including the Wallet and Referral System.

1. Open SafeSpend in your browser (or tap the installed app icon).
2. On the login screen, click "Continue with Google".
3. A Google account picker will appear — select the account you want to use.
4. Grant the requested permissions (email, name, profile picture).
5. You'll be redirected back to the app, signed in and ready to use.

2.2   Continue as Guest

Guest mode is perfect if you want to try the app immediately without an account. All your data is saved locally on your device only.

1. On the login screen, click "Continue as Guest".
2. You'll be taken straight to the onboarding flow.
3. Complete setup (currency + weekly budget).
4. Start logging expenses right away.

2.3   Profile Setup & Customization

Uploading a Profile Picture

1. Tap Settings (gear icon in the top-right header).
2. Tap your profile card at the top of the screen.
3. On the Profile screen, tap the camera icon on your avatar.
4. Choose an image from your device (max 5MB, JPG/PNG).
5. The image is automatically resized to 300×300 and saved.

Editing Your Display Name

1. From your Profile screen, tap Edit next to your name.
2. Type your preferred name.
3. Tap Save.

Changing Currency

1. Go to Settings.
2. Locate the Currency dropdown.
3. Select your preferred currency (USD, EUR, GBP, CAD, AUD, GHS, etc.).
4. All amounts update instantly across the app.

2.4   Signing Out

1. Go to Settings → Profile.
2. Scroll to the bottom and tap Sign Out.
3. Confirm the prompt. You'll return to the login screen.

Dashboard Overview

The Home screen is your financial command center. Everything important about your week is here — budget progress, health score, smart insights, and recent activity.

3.1   Home Screen Elements

A. Greeting & Time

The top of the screen shows a time-aware greeting ("Good morning / afternoon / evening") that updates every 60 seconds automatically.

B. Budget Card

A colored card showing:

• Weekly Budget — your target for the week
• Remaining — how much you still have to spend
• Progress bar — visual representation (green → yellow → red as you approach the limit)
• Spent Today — amount used since midnight
• Days Left — days remaining before the week resets (Mondays)

C. Financial Health Score

A circular gauge displaying a score from 0 to 100 based on four signals:

D. Streak Counter

Orange flame card showing consecutive weeks under budget. Keep logging to keep the streak alive!

E. Weekly Challenge

"Beat Last Week" widget comparing your spending at the same day-index. Green means you're saving more; red means you're behind.

F. Quick Stats

Three small cards: Total Spent · Transaction Count · Daily Average.

G. Recent Transactions

Last 5 expenses with category icons and tags. Tap "View All" for the full history.

H. Smart Insights

Rotating AI-generated messages such as:

• "🚨 Food spending is 2× last week — unusual jump"
• "✨ Great pace! You're tracking to save $45 this week."
• "🔁 Detected 3 recurring charges (Netflix, Spotify, Gym)"

Use the refresh icon to cycle through all available insights.

I. Badges Strip

Horizontal scroll of achievements you've earned — First Expense, Prolific Logger, Month Strong, etc.

3.2   Navigation

SafeSpend uses a bottom navigation bar for the main screens:

The header also has:

• Settings (⚙️) — top-right gear icon
• Profile (👤) — your avatar on the right

Expense Tracking

The core of SafeSpend is fast, friction-free expense logging. This chapter walks through adding, editing, and understanding your transactions.

4.1   Adding an Expense

1. From the bottom navigation, tap the Add (+) button.
2. Enter the amount (numbers only; currency prefix is automatic).
3. Optionally select a category from the 7-icon grid.
   🍽️ Food 🚗 Transport 📄 Bills 🛍️ Shopping 🎬 Fun ❤️ Health 📌 Other
4. Type a note (optional) — e.g. "KFC lunch with Alex".
5. Add tags (optional, comma-separated) — e.g. "work, urgent, recurring".
6. Confirm the date (defaults to today).
7. Tap Save Expense.

4.2   Understanding Categories

4.3   Emergency Spending Warning

If you try to log an expense larger than your remaining budget, SafeSpend shows a red warning modal:

1. Modal appears: "This will exceed your weekly budget!"
2. You're prompted to enter a reason for the emergency expense.
3. After providing justification, the expense is saved with an "emergency" tag.
4. The transaction is recorded for awareness — helpful during budget review.

4.4   Weekly Reset & Carry-Over

SafeSpend operates on a Monday-to-Sunday week. Every Monday at 00:00 local time:

• The previous week is automatically archived to your History.
• A new weekly budget begins.
• If Carry Over Savings is enabled in Settings, unused budget from last week is added to the new week.

4.5   Tags & Notes Best Practices

• Be specific in notes — "Lunch with Sarah" beats "Food" for future reference.
• Use tags for search — tag work expenses "work" to filter them later for reimbursement.
• Tag recurring expenses "monthly" or "subscription" — SafeSpend detects them automatically anyway, but explicit tags help.
• Max 8 tags per transaction; tags are lowercased automatically.

Budget Management

Your weekly budget is the foundation of SafeSpend. This chapter covers setting, adjusting, and funding it.

5.1   Setting Your Weekly Budget

During onboarding you set an initial budget. You can change it anytime:

1. From the Home screen, tap the edit icon (✏️) on your budget card.
2. You'll land on the Weekly Setup screen.
3. Adjust the Weekly Budget Amount field.
4. Toggle options:
   • Carry Over Savings — unused money rolls to next week
   • Spending Alerts — warns at 80% budget usage
5. Tap Save Setup.

5.2   Funding Your Budget (Top-Up)

Instead of fixed weekly budgets, you can "fund" your budget dynamically — simulating a real-world allowance or paycheck top-up.

1. On the Home screen, tap the plus icon (➕) on your budget card.
2. The Fund Budget screen opens with two tabs:
   • Mobile Money — top up via MTN MoMo, Vodafone Cash, AirtelTigo, or M-PESA
   • Card — credit or debit card
3. Enter the amount you want to add.
4. For Mobile Money: select network → enter phone number → tap "Pay with Mobile Money" → enter OTP (auto-generated & shown in amber banner during demo mode).
5. For Card: enter card number, cardholder name, expiry, and CVV.
6. Tap the payment button — you'll see a 2-3 second simulation overlay.
7. On success, your budget increases by the top-up amount.

5.3   Budget vs Spending Tracking

The progress bar on your budget card visually communicates status:

5.4   Understanding Your Spending Pace

Pace is calculated as: (spent / budget) ÷ (days elapsed / 7)

• Pace = 1.0 — spending exactly on target
• Pace > 1.2 — overspending; AI will warn you
• Pace < 0.7 — saving well; AI will encourage you

Mobile Money Wallet

The Wallet is a built-in savings account that lives alongside your expense tracker. Deposit money from Mobile Money, send to other SafeSpend users, or withdraw back to your Mobile Money account — all from one screen.

6.1   Accessing the Wallet

1. Open Settings (gear icon, top-right).
2. Tap the green Mobile Money Wallet card.
3. The Wallet Dashboard opens, showing your current balance.

6.2   Depositing Money

Fund your wallet from your Mobile Money account:

1. On the Wallet Dashboard, tap Add Money.
2. Select your network: MTN, Vodafone, AirtelTigo, or M-PESA.
3. Enter your Mobile Money phone number.
4. Enter the amount to deposit.
5. Tap "Pay with MoMo".
6. Wait for the 2-second processing overlay.
7. On success, your wallet balance updates immediately.

6.3   Sending Money

Send to another SafeSpend user by email or to any external Mobile Money number:

1. Tap Send on the Wallet Dashboard.
2. In the Recipient field, enter:
   • An email address → system looks up the SafeSpend user
   • A phone number → treated as external Mobile Money
3. Preview card appears confirming the recipient.
4. Enter the amount (must be ≤ your available balance).
5. Add an optional note.
6. Tap Continue.
7. Enter your 4-digit Wallet PIN (see 6.5 for setup).
8. Transfer completes instantly for SafeSpend-to-SafeSpend sends.

6.4   Withdrawing Money

Move money from your wallet back to your Mobile Money account:

1. Tap Withdraw on the Wallet Dashboard.
2. Select your network.
3. Enter the destination phone number.
4. Enter the amount (≤ available balance).
5. Tap Continue.
6. Enter your 4-digit Wallet PIN.
7. Processing overlay runs for 2 seconds; success toast appears.

6.5   Setting Up Your Wallet PIN

The first time you attempt to Send or Withdraw, a PIN setup modal appears:

1. Enter a 4-digit PIN of your choice.
2. Tap Continue.
3. Re-enter the same PIN to confirm.
4. Tap Save PIN.
5. Your PIN is hashed and saved. You'll enter it for all future wallet transactions.

6.6   Transaction History

All wallet activity appears on the Wallet Dashboard with filter tabs:

• All — every transaction
• In — money received (deposits, incoming transfers)
• Out — money sent (outgoing transfers, withdrawals)

Each row shows:

• Transaction type icon (⬇ deposit, ➡ send, ⬆ withdraw)
• Counterparty (user name or MoMo network + phone)
• Time ago label
• Amount with +/- prefix, colored by direction

6.7   Wallet Balance

Your wallet balance is computed from your transactions — never stored as a single number. This means:

• Impossible to forge a balance (fraud-proof)
• Perfect audit trail — every movement is traceable
• Balance always matches the sum of transactions

Reports & Analytics

7.1   Analytics Screen

Tap Analytics in the bottom navigation to see:

• Budget vs Spent card — headline numbers for the week
• Category breakdown pie chart — visual distribution of spending across categories
• Daily spending bar chart — spending by day of the week
• Top categories list — ranked by amount with percentage

7.2   History Screen

Tap History in the bottom navigation. Features:

• Full-text search — searches notes, tags, and amounts
• Category filter pills — tap any category to filter
• Date range dropdown — This week / 7d / 30d / 90d / All time
• Grouped by date — Today, Yesterday, weekday labels
• Summary chip — total count and total spent for current filter
• Reset button — clears all filters at once

7.3   Exporting Reports

CSV Export

1. On the History screen, tap the CSV icon (top-right).
2. A file downloads: safespend-transactions-YYYY-MM-DD.csv
3. Open with Excel, Google Sheets, or any spreadsheet tool.
4. Columns: Date, Week, Category, Note, Tags, Amount, Currency, AutoCategorized

PDF Export

1. On the History screen, tap the PDF icon (top-right).
2. A branded PDF downloads: safespend-report-YYYY-MM-DD.pdf
3. Includes: Summary card, Category breakdown table, Full transaction table, Page numbers

7.4   Understanding the Analytics Charts

Category Donut Chart

Each segment represents a category's share of your total spending. Larger slices = bigger spending.

Daily Spending Bar Chart

Shows how spending is distributed across the 7 days of the week. Weekend peaks are common; large spikes on a single day suggest impulse spending.

Notifications & Alerts

8.1   Types of Notifications

8.2   Enabling Daily Reminders

1. Go to Settings.
2. Find Daily Reminder.
3. Toggle the switch ON.
4. Your browser will ask for notification permission — click Allow.
5. Optionally change the reminder time (default 8:00 PM).

What the reminder says:

"SafeSpend Reminder 💰 — Have you logged today's expenses?"

8.3   In-App Toasts

Small notification cards slide up from the bottom for:

• Successful expense added
• Payment confirmed / failed
• PIN verified / incorrect
• Referral linked / activated
• Wallet transaction completed

They auto-dismiss after 3 seconds.

Security Features

SafeSpend is built with bank-grade security practices at every layer.

9.1   Authentication

• Google Sign-In via Firebase Authentication (OAuth 2.0)
• No passwords stored by SafeSpend — handled by Google
• Your session is token-based and auto-renews
• Sign out from any device invalidates that session

9.2   Wallet PIN

• 4-digit PIN required for all wallet transactions (send/withdraw)
• PIN is SHA-256 hashed with a random per-user salt
• Salt is generated via crypto.randomUUID() — cryptographically strong
• Raw PIN never leaves your device or reaches any server
• Three wrong attempts show a shake animation and error message

9.3   OTP Verification

Budget top-ups via Mobile Money require a 6-digit OTP:

• Auto-generated with 5-minute expiry
• Displayed in amber banner (currently demo mode)
• Auto-submit when all 6 digits entered
• "Resend" button generates a fresh code

9.4   Firestore Security Rules

Data stored in Firebase is protected by strict server-side rules:

• Users can only write their own data — can't modify another user's profile, wallet, or referrals
• Wallet balance is computed, never stored — impossible to forge
• Transactions are immutable — once created, cannot be edited or deleted
• Self-referral blocked — cannot refer yourself
• Reward amounts capped — referral rewards limited to $100 max

9.5   Fraud Prevention

9.6   Best Practices for Users

1. Use a strong PIN — avoid 1234, 0000, or your birth year
2. Don't share your Google password — Google Sign-In gives full access
3. Sign out on shared devices — public computers especially
4. Keep the app updated — pull the latest version regularly
5. Review your transactions weekly — catch anything unexpected quickly
6. Enable browser notifications carefully — only allow trusted apps

Referral System

Invite friends to SafeSpend and earn commission when they sign up and start using the app.

10.1   How It Works

1. You share your unique referral link with a friend.
2. They click the link and sign up with Google.
3. Their account is automatically linked as your referral (status: Pending).
4. When they log their first expense, the referral becomes Active.
5. You earn a fixed commission (5 units in your chosen currency).

10.2   Accessing the Referral Dashboard

1. Go to Settings.
2. Tap the purple/indigo Refer & Earn card.
3. The dashboard opens with your code, link, and stats.

10.3   Sharing Your Link

Your referral code has the format SAFE-XXXXX (e.g. SAFE-X9K2P).

Your link looks like: https://yourapp.url/?ref=SAFE-X9K2P

The dashboard provides four share methods:

10.4   Tracking Your Referrals

The Referral Dashboard shows three key stats:

10.5   Withdrawing Your Earnings

1. On the Referral Dashboard, tap Request Withdrawal.
2. Select method: Mobile Money or Bank Transfer.
3. Enter your account details (phone number or bank info).
4. Enter the amount — minimum is 20 units.
5. Tap Submit Request.
6. Processing takes 3-5 business days.

10.6   Fraud Prevention

The following are automatically blocked:

• Self-referrals — can't refer yourself
• Duplicate referrals — user can only be referred once
• Same-device farming — device fingerprinting detects multiple accounts on one device
• Reward inflation — cap of 100 per referral at the database rule level

Step-by-Step Quick Start

New to SafeSpend? Follow this walkthrough to get set up and using the app like a pro in under 5 minutes.

🚀 Day 1: Setup (5 minutes)

1. Open the app at your SafeSpend URL or from your home screen icon.
2. Sign in with Google — tap the big blue button and pick your account.
3. Complete onboarding:
   • Your name is pre-filled from Google
   • Choose your currency (e.g. USD, GHS)
   • Set your weekly budget (start with something realistic, say $150)
   • Tap Get Started
4. Add your first expense:
   • Tap the + button in the bottom nav
   • Enter amount (e.g. $12)
   • Type a note: "Lunch at Chipotle"
   • Tap Save Expense
   • Watch the app auto-categorize it as Food
5. Explore your Health Score — the gauge on Home updates automatically.

📅 Daily Routine (< 1 minute/day)

1. Each evening, open the app.
2. Tap + and log today's expenses.
3. Check your Health Score and AI insight.
4. Close the app. You're done.

📊 Weekly Review (5 minutes, every Sunday)

1. Open Analytics — see where your money went.
2. Note your top category — was it expected?
3. Check History — spot any suspicious or forgotten expenses.
4. Reflect on your Health Score and Streak.
5. Adjust next week's budget if needed.

💪 Level Up: Advanced Features

• Week 2: Try the Mobile Money Wallet. Deposit a small amount.
• Week 3: Invite a friend via the Referral System.
• Week 4: Export your month as PDF and review.
• Month 2: Upload a profile picture, enable Dark Mode, set a daily reminder.

Troubleshooting

Running into issues? Most problems have quick fixes below.

12.1   Sign-In Issues

"Sign-in failed, please try again"

1. Open browser DevTools (F12) → Console tab.
2. Look for [Auth] Sign-in error: — it shows the exact Firebase error code.
3. Match the code to these fixes:
   • auth/popup-blocked → Allow popups for this site in browser settings
   • auth/unauthorized-domain → Add localhost to Firebase Console → Authentication → Settings → Authorized domains
   • auth/operation-not-allowed → Enable Google provider in Firebase Console → Authentication → Sign-in method
   • auth/network-request-failed → Check your internet connection

Sign-in popup closes immediately

• Popup blockers are likely active — check browser toolbar for blocked popup icon
• Try clicking the Google button again; browsers sometimes need a second try

12.2   App Shows Old Version

If you've just updated and the app still looks like the old one:

1. Press Ctrl+Shift+R (or ⌘+Shift+R on Mac) to hard-reload.
2. If still old, open DevTools → Application tab → Service Workers → click Unregister.
3. Reload the page once more.
4. Alternatively, tap the "Clear cache & reload" button in any error banner.

12.3   OTP Not Appearing

Budget top-up OTP should show in an amber banner inside the OTP modal.

• Make sure you're using Mobile Money (not Card) — OTP only appears for MoMo
• Wait 1-2 seconds after clicking Pay — the banner appears after generation
• If the banner is empty, tap Resend OTP to generate a new one

12.4   Wallet Issues

12.5   Time Display Incorrect

If the greeting says "Good morning" when it's evening:

1. The greeting refreshes every 60 seconds automatically.
2. If it's still wrong, the tab may have been inactive — switch away and back to trigger a refresh.
3. Hard-reload to reset all timers.

12.6   Referral Link Not Working

12.7   Data Not Syncing Across Devices

• Only Google Sign-In accounts sync. Guest mode is device-only.
• Make sure you're signed in with the same Google account on both devices.
• Firestore must be enabled in Firebase Console for sync to work.
• Check your internet connection — sync requires a live connection.

12.8   Can't Install as PWA

• Use Chrome, Edge, or Safari (other browsers may not support PWA install)
• The app must be served over HTTPS (not http://localhost for install prompt)
• Look for the install icon in the URL bar, or use browser menu → "Install SafeSpend"

Frequently Asked Questions

Conclusion

Summary of What You Learned

• ✅ How to sign up, log in, and set up your profile
• ✅ How to add, categorize, and tag expenses
• ✅ How to manage your weekly budget and carry over savings
• ✅ How to use the Mobile Money Wallet for deposits, sends, and withdrawals
• ✅ How to interpret your Financial Health Score and AI Insights
• ✅ How to export reports as CSV or PDF
• ✅ How to invite friends and earn referral commissions
• ✅ How to keep your account secure with PIN and OTP
• ✅ How to troubleshoot common issues

Our Philosophy

SafeSpend is built on the belief that small, consistent actions compound into big financial wins. Logging a single expense takes 10 seconds. Doing it daily for a year gives you 365 data points about your life — more than most people ever have. That's the foundation for real financial clarity.

Future Improvements

We're actively working on:

• 🔌 Real Mobile Money API integration (MTN, Flutterwave, Paystack)
• 📧 Email notifications for transactions and weekly summaries
• 📸 Receipt photo upload with automatic OCR extraction
• 🎙️ Voice input for quick expense logging
• 👥 Multi-user households with shared budgets
• 🏦 Bank account sync via Plaid/Mono for automatic imports
• 🔔 Firebase Cloud Messaging for cross-device push notifications

Getting Help

If you run into issues:

1. Consult Chapter 12: Troubleshooting first
2. Check the Chapter 13: FAQ
3. Open browser DevTools (F12) and check the console for detailed errors
4. Contact SafeSpend support through the app's settings

Stay Connected

Follow updates, request features, and share feedback:

• 🌐 Website: Your SafeSpend URL
• 💻 Source Code: github.com/biorkenexus-gh/safespend
• 📧 Support: through in-app settings