{"id":29805239,"url":"https://github.com/useraar/financaar-mobile","last_synced_at":"2025-10-14T07:15:20.949Z","repository":{"id":303546024,"uuid":"1015852286","full_name":"UserAAR/FinancAAR-Mobile","owner":"UserAAR","description":"A smart and user-friendly personal finance manager that helps you track, analyze, and control your cash, cards, and debts with ease.","archived":false,"fork":false,"pushed_at":"2025-07-08T22:06:58.000Z","size":9146,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-28T13:38:19.305Z","etag":null,"topics":["expo","finance-management","mobile-app","react-native"],"latest_commit_sha":null,"homepage":"https://financaar.rf.gd","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UserAAR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-08T06:16:23.000Z","updated_at":"2025-07-08T22:07:01.000Z","dependencies_parsed_at":"2025-07-08T07:52:16.154Z","dependency_job_id":null,"html_url":"https://github.com/UserAAR/FinancAAR-Mobile","commit_stats":null,"previous_names":["useraar/financaar-mobile"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UserAAR/FinancAAR-Mobile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UserAAR%2FFinancAAR-Mobile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UserAAR%2FFinancAAR-Mobile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UserAAR%2FFinancAAR-Mobile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UserAAR%2FFinancAAR-Mobile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UserAAR","download_url":"https://codeload.github.com/UserAAR/FinancAAR-Mobile/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UserAAR%2FFinancAAR-Mobile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018219,"owners_count":26086303,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["expo","finance-management","mobile-app","react-native"],"created_at":"2025-07-28T13:35:31.867Z","updated_at":"2025-10-14T07:15:20.933Z","avatar_url":"https://github.com/UserAAR.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.png\" alt=\"FinancAAR Logo\" width=\"300\" /\u003e\n\n\u003cbr/\u003e\n\n\u003cimg src=\"https://img.shields.io/badge/FinancAAR-%20Finance%20Manager-blueviolet?style=for-the-badge\" alt=\"FinancAAR Finance Manager Badge\" /\u003e\n\n\u003cbr/\u003e\n\n\u003cstrong\u003eOffline-first, privacy-focused personal finance manager built with React Native\u003c/strong\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/UserAAR/FinancAAR-Mobile?style=social\" alt=\"Stars\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/forks/UserAAR/FinancAAR-Mobile?style=social\" alt=\"Forks\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/issues/UserAAR/FinancAAR-Mobile\" alt=\"Issues\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-Proprietary-red.svg\" alt=\"License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/UserAAR/FinancAAR-Mobile\" alt=\"Last Commit\" /\u003e\n\u003c/p\u003e\n\n\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://financaar.rf.gd\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Live%20Demo-%F0%9F%9A%80%20Open-blueviolet?style=for-the-badge\u0026logo=kdenlive\" alt=\"Live Demo\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/UserAAR/FinancAAR-Mobile/releases\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Release%20Notes-%E2%9C%A8%20View-green?style=for-the-badge\u0026logo=logstash\" alt=\"Release Notes\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/UserAAR/FinancAAR-Mobile/wiki\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Documentation-%F0%9F%93%9A%20Read-blue?style=for-the-badge\u0026logo=readthedocs\" alt=\"Documentation\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/UserAAR/FinancAAR-Mobile/issues\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Report%20Bug-%F0%9F%90%9B%20Submit-red?style=for-the-badge\u0026logo=bugatti\" alt=\"Report Bug\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/UserAAR/FinancAAR-Mobile/issues\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Request%20Feature-%E2%9C%A8%20Suggest-blueviolet?style=for-the-badge\u0026logo=gitbook\" alt=\"Request Feature\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n# FinancAAR – Personal Finance Manager \n\nFinancAAR is a cross-platform (Android \u0026 iOS) personal-finance manager that helps you **track income \u0026 expenses, manage debts, analyse spending trends and generate beautifully formatted financial reports** – all offline and completely private.  \nThis repository hosts the *production-ready source code* for the mobile client.\n\n---\n\n## ✨ Key Features\n\n| Area | Highlights |\n|------|------------|\n| **Accounts** | • Unlimited *Cash* and *Card* accounts  \n• Custom colours \u0026 emoji icons  |\n| **Transactions** | • Fast add / edit flow with category selector  \n• Supports *income*, *expense*, *transfer*, *debt payment* |\n| **Debts** | • Track who you owe \u0026 who owes you  \n• Status updates (paid / unpaid) |\n| **Smart Notifications** | • Daily summary \u0026 personalised tips  \n• Schedules handled locally (works offline) |\n| **Security** | • PIN (4 \u0026 6 digits)  \n• Biometric unlock (Fingerprint / Face ID) |\n| **Analytics** | • Charts for last 7 days / month / customised ranges  |\n| **Financial Reports** | • Multi-select data types (Transactions, Debts, Balances, Categories, Accounts)  \n• Preset ranges (1 day, 1 week, 1/3/6 months, all time)  \n• Export to **CSV**, **XLSX**, **PDF**  \n• Share sheet **or** direct download to `/Download` (Android SAF)  |\n| **Theming** | • Light / Dark / System  |\n| **Offline-first** | • Local SQLite DB (no remote server needed) |\n\n---\n\n## 🛠️ Tech Stack\n\n* **React Native 0.79** (Hermes)  \n* **Expo SDK 53**  \n* **TypeScript 5**  \n* `expo-file-system`, `expo-print`, `expo-notifications`, `expo-secure-store`, `expo-local-authentication`, `expo-sqlite`  \n* **React Navigation 7** (Stack \u0026 Bottom Tabs)  \n* **Reanimated 3**, **Gesture Handler 2**  \n* Charts – `react-native-chart-kit`  \n* XLSX – `xlsx 0.18` (SheetJS)  \n\n### Folder Structure (simplified)\n\n```txt\nsrc/\n  components/        # Reusable UI elements (AccountCard, Toast…)\n  screens/           # App screens, incl. Settings \u0026 Reports modal\n  navigation/        # React-Navigation stacks \u0026 tabs\n  contexts/          # Theme \u0026 Auth contexts\n  hooks/             # Custom hooks (biometric, secure storage, notifications)\n  services/          # Local \u0026 push notification helpers\n  utils/             # DB wrapper, currency helper, exporter (CSV/XLSX/PDF)\n  types/             # Global type declarations\n```\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n* **Node.js ≥20**  \n* **Expo CLI** – `npm i -g expo-cli`  \n* A physical Android / iOS device **or** simulator/emulator\n\n### Local Setup\n\n```bash\n# 1. Clone repo\n$ git clone https://github.com/UserAAR/FinancAAR-Mobile.git \u0026\u0026 cd FinancAAR-Mobile\n\n# 2. Install deps\n$ npm i           # or yarn\n\n# 3. Start dev server\n$ npm run start   # Expo dev menu\n```\n\n*Press **\"a\"** to open Android Emulator, **\"i\"** for iOS Simulator or scan QR with Expo Go.*\n\n### Environment Variables\n\nThis project does **not** require remote API keys.  \nAll storage is local; only system permissions are requested at runtime (Notifications, Storage, Biometric).\n\n---\n\n## 📦 Building for Production\n\n### Android (AAB / APK)\n\n```bash\n# Install EAS CLI if needed\nyarn global add eas-cli   # or npm i -g eas-cli\n\n# Configure (first time only)\neas build:configure\n\n# Cloud build (AAB)\neas build -p android --profile production\n```\n\nThe build finishes with a download URL you can attach to a GitHub Release.\n\n### iOS (IPA)\n\n```bash\neas build -p ios --profile production\n```\n\n*Requires Apple ID credentials \u0026 certificates (managed by EAS).*  \n\n---\n\n## 🗂️ Database Schema\n\nSQLite tables are created automatically on first run.\n\n| Table | Fields (excerpt) |\n|-------|------------------|\n| **accounts** | id (PK), name, type (cash/card), balance, color, emoji, createdAt |\n| **categories** | id (PK), name, type (income/expense) |\n| **transactions** | id (PK), amount, type, date, title, categoryId (FK), accountId (FK) |\n| **debts** | id (PK), personName, amount, status, date |\n\nSee `src/utils/database.ts` for full schema \u0026 helper methods.\n\n---\n\n## 🔐 Permissions\n\n| Platform | When | API |\n|----------|------|-----|\n| Android | Export → Download | `StorageAccessFramework` (WRITE_EXTERNAL_STORAGE fallback API \u003c 33) |\n| Android \u0026 iOS | Reporting → Share | `expo-sharing` |\n| Android \u0026 iOS | Biometric Login | `expo-local-authentication` |\n| Android \u0026 iOS | Notifications | `expo-notifications` (foreground \u0026 scheduled) |\n\nAll permissions are requested **just-in-time**, with graceful handling if denied.\n\n---\n\n## 🧑‍💻 Contributing\n\n1. Fork \u0026 clone repo.  \n2. `git checkout -b feat/my-feature`  \n3. Commit with conventional-commit messages.  \n4. `git push` and open a PR.  \n5. CI/Lint must pass before merge.\n\n### Code Style\n\n* **TypeScript strict**  \n* ESLint + Prettier configured via Expo defaults.  \n* Commit messages follow *Conventional Commits*.\n\n### Issue \u0026 Pull Request Workflow\n\n* Please use the **GitHub issue templates** located in `.github/ISSUE_TEMPLATE` when reporting bugs or proposing features. Providing complete information helps us triage and resolve tickets faster.\n* Pull Requests must follow the **PR template** (`.github/PULL_REQUEST_TEMPLATE.md`) and complete the checklist before review.\n* For general questions or support, open a thread in **GitHub Discussions** instead of filing an issue.\n* By participating in this project you agree to abide by our **[Code of Conduct](.github/CODE_OF_CONDUCT.md)**.\n* Detailed development guidelines are available in **[CONTRIBUTING.md](.github/CONTRIBUTING.md)**.\n\n---\n\n## 📚 Documentation\n\nDetailed technical documentation now lives in the [`docs/`](./docs) directory:\n\n- [Architecture Overview](docs/architecture-overview.md)\n- [Database Schema](docs/database-schema.md)\n- [Architecture Decision Records](docs/adr/)\n\nFor general questions or implementation discussions, please open a thread in **[GitHub Discussions](https://github.com/UserAAR/FinancAAR-Mobile/discussions)**.\n\n---\n\n## 📝 License\n\nFinancAAR is distributed under a **Proprietary License**. You may freely download and use the compiled APK for personal, non-commercial purposes. Any other use—including but not limited to reproducing, modifying, or redistributing the source code—requires prior written permission from **UserAAR**. See [`LICENSE`](LICENSE) for full terms.\n\n---\n\n## 🙏 Acknowledgements\n\n* [Expo](https://expo.dev) – making React Native painless.  \n* [SheetJS](https://github.com/SheetJS/sheetjs) for XLSX export.  \n* [React Navigation](https://reactnavigation.org) \u0026 community libraries.\n\n## 📊 **FINANCIAL CALCULATION METHODOLOGY**\n\n### **Mathematically Proven Formulas Used:**\n\n#### **Net Savings Calculation (Real Wealth Building):**\n```\nNet Savings = Current Total Assets - Previous Period Total Assets\n```\n- **Source**: Standard financial accounting principles\n- **Why Accurate**: Measures actual wealth accumulation, not just cash flow\n- **Implementation**: `database.calculateNetSavings()`\n\n#### **Savings Rate Calculation (Industry Standard):**\n```\nSavings Rate = (Net Savings / Gross Income) × 100\n```\n- **Source**: Financial Independence community standards, CFP Board recommendations\n- **Why Accurate**: Shows true percentage of income building wealth\n- **Implementation**: `database.calculateSavingsRate()`\n\n#### **Cash Flow Savings Rate (Traditional Method):**\n```\nCash Flow Rate = ((Income - Expenses) / Income) × 100\n```\n- **Source**: Traditional budgeting methods\n- **Use Case**: Month-to-month spending analysis\n- **Limitation**: Doesn't account for asset changes or transfers\n\n#### **Financial Health Score (0-100 Composite):**\n```\nHealth Score = Savings Rate (40%) + Net Savings (30%) + Trend (20%) + Balance (10%)\n```\n- **Methodology**: Weighted composite based on financial planning best practices\n- **Benchmarks**: \n  - 80-100: Excellent financial health\n  - 60-79: Good financial health \n  - 40-59: Fair, needs improvement\n  - 0-39: Poor, requires immediate attention\n\n### **Data Sources \u0026 Accuracy:**\n- ✅ **All Account Balances**: Real-time from user's actual accounts\n- ✅ **All Transactions**: Complete transaction history\n- ✅ **Category Spending**: Accurate categorized expenses\n- ✅ **Income Tracking**: All income sources recorded\n- ✅ **Time Periods**: 3-month, 6-month, 1-year analysis\n\n### **Mathematical Verification:**\n- ✅ **Zero Sum Principle**: All money flows tracked\n- ✅ **Double Entry**: Account balance changes = transaction totals\n- ✅ **Period Consistency**: Calculations verified across time periods\n- ✅ **Industry Standards**: Formulas match financial planning guidelines\n\n---\n\n## Features \n\n### Why FinancAAR?\n\n- ✨ **Offline-First Personal Finance** – All data is stored locally using SQLite; no servers, no tracking.\n- 🏦 **Unlimited Accounts** – Create as many *Cash* and *Card* accounts as you need with custom colours \u0026 emoji icons.\n- 💸 **Comprehensive Transactions** – Fast add / edit flow supporting *income*, *expense*, *transfer* and *debt payment* types.\n- 🤝 **Debt Management** – Track who you owe (or who owes you), with status updates and visual summaries.\n- 📊 **Advanced Analytics** – Interactive charts for the last 7 days, month or any custom range; spot spending trends instantly.\n- 🧠 **AI Insights** – AI-powered analysis delivers actionable tips to optimise your budget (processed fully on-device).\n- 🔔 **Smart Notifications** – Daily summary \u0026 personalised suggestions, scheduled locally so they work even when offline.\n- 🔐 **Solid Security** – 4- \u0026 6-digit PIN, plus biometric unlock (Fingerprint / Face ID).\n- 📑 **Rich Reporting \u0026 Export** – Generate beautifully formatted **CSV**, **XLSX** and **PDF** reports; share via system sheet or save directly to `/Download`.\n- 🎨 **Dynamic Theming** – Light, Dark \u0026 System modes with instant switching.\n- 🚀 **Cross-platform** – Runs smoothly on Android \u0026 iOS, thanks to Hermes \u0026 Reanimated 3 optimisations.\n- 📈 **Financial Health Score** – Composite metric (0-100) based on savings rate, net savings \u0026 balance trends.\n\n---\n\n\u003cp align=\"center\"\u003e🚀Take charge of your financial journey with \u003cstrong\u003eFinancAAR\u003c/strong\u003e–where your money is in control and your future is secure💰\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuseraar%2Ffinancaar-mobile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuseraar%2Ffinancaar-mobile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuseraar%2Ffinancaar-mobile/lists"}