PocketGuru

PocketGuru is a local-first personal finance companion built with React Native 0.83 and TypeScript. It helps you keep tabs on budgets, expenses, savings goals, and live gold prices without sending sensitive data to third‑party clouds. The app favors calm UI cues, actionable insights, and privacy-first defaults (biometric auth, encrypted storage, offline support).

---

Features

• Financial Dashboard – net worth snapshot, surplus/deficit trend, top categories, savings rate, 50/30/20 hints.
• Income & Expenses – quick add flows, recurring transactions, location hints, photo receipts + OCR, CSV/PDF export.
• Budgets – monthly/quarterly/annual envelopes, “near limit” warnings, unused rollover, visual progress.
• Savings & Goals – bucketized goals, windfall advisor, emergency-fund coverage, milestone nudges, serenity copy.
• Gold Tracker – live quotes from GoldAPI, range/volatility analytics, holdings performance, alerts, buy/sell watch zones.
• Security & Privacy – biometric unlock, encrypted async storage, no analytics, offline-first architecture, local backups.
• Utilities – React Navigation tab stack, Victory Native charts, Notifee notifications, SQLite storage, Expo asset/font stubs removed.

---

Project Structure

NewApp/
├── android/               # Native Android project
├── ios/                   # Native iOS project
├── src/
│   ├── components/        # Reusable UI atoms/molecules
│   ├── data/              # Static fixtures + seed data
│   ├── hooks/             # React hooks (finance, gold, savings...)
│   ├── models/            # TypeScript interfaces & enums
│   ├── navigation/        # React Navigation stacks/tabs
│   ├── providers/         # Context providers (FinanceProvider, Theme)
│   ├── screens/           # Feature screens (Dashboard, Expenses, Savings, Gold, Income, Advisor, Settings)
│   ├── services/          # API clients, OCR service, notifications
│   ├── storage/           # SQLite repositories, secure storage helpers
│   ├── theme/             # Light/dark palettes, typography, spacing tokens
│   └── App.tsx            # Root entrypoint
├── .env.example           # Required environment variables template
├── package.json
├── tsconfig.json
└── README.md

---

Prerequisites

Dependency	Version / Notes
Node.js	>= 20.19.4 (aligns with React Native 0.83 support)
npm	v10+ (or Yarn 1.22+, but npm is default)
Java JDK	17 LTS (for Android builds)
Android Studio	Flamingo+ w/ SDK 34+
Xcode (macOS)	15+ (for iOS builds)
Watchman (macOS)	Optional, speeds up Metro

Ensure you’ve followed the official React Native environment setup guide for your platform.

---

Installation & Setup

1. Clone and install dependencies

   git clone <repo-url> pocketguru
   cd pocketguru
   npm install

2. Configure environment variables

   • Duplicate .env.example to .env.
   • Fill in values:

     GOLD_API_BASE_URL=https://www.goldapi.io/api
     GOLD_API_KEY=goldapi-xxxxxxxxxx
     DEFAULT_CURRENCY=USD
     NOTIFICATION_CHANNEL=finance-alerts

   • Rebuild native apps after modifying .env because react-native-config loads values at build time.

3. iOS (macOS only)

   cd ios
   bundle install        # only first time
   bundle exec pod install
   cd ..

4. Start Metro Bundler

   npm start

5. Run the app

   # Android
   npm run android
   
   # iOS (requires simulator or connected device)
   npm run ios

---

Useful Scripts

Command	Description
npm start	Launch Metro bundler
npm run android	Build & install on Android emulator/device
npm run ios	Build & install on iOS simulator/device
npm run typecheck	TypeScript project-wide type check
npm run lint	ESLint (configure in package.json when ready)
npm test	Run Jest tests (snapshot/unit)

---

Development Notes

• Local Data: SQLite (via react-native-sqlite-storage) stores budgets/expenses/savings. Gold alerts and watch zones live in repositories under src/storage.
• Security: Sensitive payloads (biometrics, encrypted storage) rely on react-native-biometrics and react-native-encrypted-storage. Ensure you enable device security for full benefit.
• Gold API: src/services/goldApi.ts handles latest + historical quotes. Historical API is rate limited—cache results where possible to avoid throttling.
• Push/Local Notifications: Notifee powers price alerts and savings milestones. Android needs a notification channel (see .env); iOS needs push capabilities configured in Xcode if you enable remote notifications later.
• Styling: Centralized tokens live in src/theme. Favor useTheme() for colors to support light/dark modes seamlessly.
• Navigation: Root tab navigation sits in src/navigation/RootNavigator.tsx, with nested stacks for flows like Expenses > Details.
• Testing: Placeholder tests exist under __tests__/. Add regression tests for regression-prone hooks (finance math, gold alerts, persistence) before big refactors.

---

Troubleshooting

• Metro stuck / weird caching: stop Metro, clear cache npm start -- --reset-cache.
• Android build fails on jcenter(): remove deprecated repositories from android/build.gradle or upgrade libraries—we already patched react-native-sqlite-storage.
• “Gold API request failed”: confirm .env is configured, rebuild app, and verify token via curl (see GoldAPI docs). Rate limits may return HTTP 429, handled gracefully in UI.
• Type errors after editing models: run npm run typecheck to catch cross-module breaks before launching a build.

---

Roadmap Ideas

• Advisor “chat” mode powered by local rules (no remote LLMs).
• Receipt classification model caching for offline use.
• Multi-currency budgeting (per category exchange rates).
• Subscription tracking with renewal alerts.

---

License

This project is private/personal use. If you plan to distribute, ensure you’ve reviewed the licenses of bundled libraries (React Native, Notifee, GoldAPI terms, etc.).

---

Happy budgeting! 💸