{"id":48452474,"url":"https://github.com/niyazmft/financial_tracker","last_synced_at":"2026-04-06T21:03:24.929Z","repository":{"id":334601937,"uuid":"1086697809","full_name":"niyazmft/financial_tracker","owner":"niyazmft","description":"🚀 A modern, Personal finance tracker and wealth management dashboard. Built with Vue 3, Pinia, PrimeVue 4, and Node.js. Featuring automated NocoDB integration, anomaly detection, and real-time spending analysis.","archived":false,"fork":false,"pushed_at":"2026-03-18T21:50:06.000Z","size":311,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-19T10:31:07.858Z","etag":null,"topics":["anomaly-detection","expense-manager","finance-tracker","fintech","firebase-analytics","firebase-authentication","javascript","nocodb","nodejs","personal-finance","primevue","self-hosted","vue3","wealth-management"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niyazmft.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,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T19:18:20.000Z","updated_at":"2026-03-18T21:50:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/niyazmft/financial_tracker","commit_stats":null,"previous_names":["niyazmft/financial_tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/niyazmft/financial_tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niyazmft%2Ffinancial_tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niyazmft%2Ffinancial_tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niyazmft%2Ffinancial_tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niyazmft%2Ffinancial_tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niyazmft","download_url":"https://codeload.github.com/niyazmft/financial_tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niyazmft%2Ffinancial_tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31489427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["anomaly-detection","expense-manager","finance-tracker","fintech","firebase-analytics","firebase-authentication","javascript","nocodb","nodejs","personal-finance","primevue","self-hosted","vue3","wealth-management"],"created_at":"2026-04-06T21:03:23.275Z","updated_at":"2026-04-06T21:03:24.923Z","avatar_url":"https://github.com/niyazmft.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FinTrack - Smart Financial Tracker\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Vue](https://img.shields.io/badge/Vue.js-3.x-4fc08d.svg)](https://vuejs.org/)\n[![Vite](https://img.shields.io/badge/Vite-6.x-646cff.svg)](https://vitejs.dev/)\n\nFinTrack is a comprehensive, modern personal finance management application. Built with **Vue 3** and **Node.js**, it provides an intuitive interface to track income, manage budgets, analyze spending trends, and monitor subscriptions—all in one place.\n\n## 🚀 Features\n\n- **Centralized Dashboard**: Unified view of your financial health with interactive balance forecasting.\n- **Transaction Management**: Robust filtering, categorization, and smart import (CSV/JSON).\n- **Intelligent Tagging**: Automate transaction categorization with custom rules.\n- **Budget Manager**: Set monthly targets per category with real-time progress tracking.\n- **Installment Plans**: Manage long-term payments with automatic schedule generation and rebalancing.\n- **Subscription Tracker**: Identify and track recurring payments with smart suggestions from your transaction history.\n- **Spending Analysis**: Deep-dive into spending patterns with category-based breakdowns and YoY trends.\n- **Secure Auth \u0026 Analytics**: Powered by **Firebase Authentication** for secure sign-up and session management, and **Firebase Analytics** to track user interactions and improve the experience.\n- **Smart Notifications**: Transactional emails for welcome messages and password resets (Dev-friendly with Ethereal).\n\n## 📖 Core Concepts\n\nUnderstanding how FinTrack processes your data helps you get the most out of the application.\n\n### 🏷️ Transaction Categorization \u0026 Tagging\n\nFinTrack uses a two-tier approach to organize your spending:\n\n- **Manual Categories**: Every transaction is assigned to a category (e.g., \"Groceries\", \"Salary\"). Categories are either typed as `earning` or `spending`.\n- **Intelligent Tagging Rules**: You can create custom rules (e.g., \"If description contains 'Amazon', set category to 'Shopping'\"). When you import transactions, these rules are applied automatically to save time.\n\n### 💰 Monthly Income Estimation\n\nThe application automatically calculates your \"Estimated Monthly Income\" by averaging all `earning` category transactions from the last 6 months. This estimate is used as the baseline for your dashboard's balance forecasting.\n\n### 📊 Budget Management\n\nBudgets are set per category for a specific date range. FinTrack tracks your real-time spending against these targets.\n\n- **Spent Amount**: Only negative transactions within the budget's category and date range are counted.\n- **Visual Progress**: Progress bars turn from green to red as you approach or exceed your limits.\n\n### 🕵️ Anomaly Detection\n\nThe system monitors your spending patterns to identify unusual activity:\n\n- **Logic**: It compares recent transactions (last 30 days) against your historical average (90-day window) for each category.\n- **Sensitivity**: If a transaction is `X` times higher than your average (where `X` is your sensitivity setting), it triggers an alert.\n\n## 📸 Previews\n\n| Dashboard | Transactions |\n| :---: | :---: |\n| \u003cimg src=\"https://github.com/user-attachments/assets/267d59e3-f867-4332-a049-4492e007e287\" width=\"400\" /\u003e | \u003cimg src=\"https://github.com/user-attachments/assets/191f56bb-6b1d-420d-8b4a-fd4616a46051\" width=\"400\" /\u003e |\n\n| Budget Manager | Spending Analysis |\n| :---: | :---: |\n| \u003cimg src=\"https://github.com/user-attachments/assets/620b707f-ee50-4ed4-a11c-95bce0d8b002\" width=\"400\" /\u003e | \u003cimg src=\"https://github.com/user-attachments/assets/9dceb379-edaf-4b79-a794-f5c97399f6b7\" width=\"400\" /\u003e |\n\n## 🏗️ Architecture \u0026 Dependencies\n\nFinTrack follows a clean, modular architecture separating the frontend, backend, and infrastructure layers.\n\n- **Frontend**: Vue 3 (Composition API), Pinia (State), PrimeVue (UI), Tailwind CSS.\n- **Backend**: Node.js, Express.js (REST API).\n- **Data Layer**: NocoDB (Low-code DB interface) on top of PostgreSQL.\n- **Authentication \u0026 Analytics**: Firebase Admin SDK (Backend), Firebase Client SDK (Frontend).\n- **Infrastructure**: Docker \u0026 PM2 configurations (located in `infrastructure/`).\n\n## 🛠️ DevOps \u0026 Tooling\n\n- **CI/CD Pipeline**: Automated testing (Mocha/Vitest) and build checks via **GitHub Actions**.\n- **Logging**: Structured logging with **Winston**, supporting daily rotation and separate error logs.\n- **Email Service**: **Nodemailer** with Handlebars templates. Uses **Ethereal** (fake SMTP) in dev for easy testing.\n- **Testing**:\n  - **Backend**: Mocha + Sinon + Supertest\n  - **Frontend**: Vitest + Vue Test Utils\n- **Code Quality**: Project-wide linting via **ESLint** (JS, Vue, JSON), **Stylelint** (CSS/Tailwind v4), and **Markdownlint**. Unified under `pnpm run lint:all`.\n- **Git Hooks**: Automated pre-commit hooks via **Husky** and **lint-staged** ensure all staged code is automatically fixed and validated before being committed.\n\n## 🤖 AI-Ready Development\n\nFinTrack is designed to be AI-native and is fully compatible with the **Gemini CLI** and other AI-assisted development tools.\n\n- **[GEMINI.md](GEMINI.md)**: This file contains the primary context, architectural protocols, and mandatory coding standards for AI agents. It ensures that any AI-generated code or refactoring remains consistent with the project's established patterns and design principles.\n- **Protocol-Driven**: The codebase follows a strict service-layer architecture and TDD workflow, making it highly predictable and safe for automated interventions.\n\n## 🗄️ Database Setup (NocoDB)\n\nFinTrack utilizes NocoDB to manage its data. Ensure the following tables are set up in your NocoDB instance with these specific fields:\n\n### Core Tables\n\n1. **bank\\_statments (Transactions)**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `date`: Date\n    - `amount`: Number (Negative for expenses, positive for income)\n    - `bank`: Text\n    - `description`: Text\n    - `ref_no`: Text (Reference number for bank transactions)\n    - `categories_id`: Link to categories table\n    - `is_deleted`: Boolean\n\n2. **categories**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `category_name`: Text\n    - `type`: Text (e.g., 'spending', 'earning')\n    - `is_deleted`: Boolean\n\n3. **subscriptions**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `name`: Text\n    - `amount`: Number\n    - `currency`: Text (Default: 'TRY')\n    - `billing_cycle`: Text (e.g., 'monthly', 'weekly', 'bi-weekly')\n    - `status`: Text (e.g., 'Active', 'Inactive')\n    - `start_date`: Date\n    - `next_payment_date`: Date\n    - `auto_renewal`: Boolean\n    - `notes`: Long Text\n    - `categories_id`: Link to categories table\n\n4. **items**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `item_name`: Text\n    - `categories_id`: Link to categories table\n    - `is_deleted`: Boolean\n\n### Financial Planning \u0026 Management\n\n1. **saving\\_goals**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `goal_name`: Text\n    - `target_amount`: Number\n    - `priority`: Number (Integer)\n    - `target_date`: Date\n    - *(Note: `current_amount` is dynamically calculated by the application.)*\n\n2. **budget\\_manager**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `target_amount`: Number\n    - `start_date`: Date\n    - `end_date`: Date\n    - `is_active`: Boolean\n    - `categories_id`: Link to categories table\n\n3. **installments\\_per\\_record**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `installment_payment`: Number\n    - `start_date`: Date\n    - `paid`: Boolean\n    - `items_id`: Link to items table\n    - `categories_id`: Link to categories table\n    - `is_deleted`: Boolean\n\n4. **tagging\\_rules**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `keyword`: Text\n    - `type`: Text (e.g., 'contains')\n    - `categories_id`: Link to categories table\n\n5. **user\\_settings**\n    - `Id`: Primary Key\n    - `user_id`: Text (User's Firebase UID)\n    - `name`: Text\n    - `email`: Text (Email format)\n    - `monthly_income_estimate`: Number\n    - `currency`: Text (e.g., 'TRY')\n    - `time_zone`: Text\n    - `warning_threshold`: Number\n    - `anomaly_detection_enabled`: Boolean\n    - `anomaly_detection_sensitivity`: Number\n    - `dismissed_warnings`: JSON\n    - `onboarding_completed`: Boolean\n\n## 🏁 Getting Started\n\n### Prerequisites\n\n- Node.js (v18 or higher)\n- Docker \u0026 Docker Compose\n- A Firebase Project (for Auth \u0026 Analytics)\n\n### Installation\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/niyazmft/financial_tracker.git\n   cd financial_tracker\n   ```\n\n2. **Configuration**\n   - Copy the example environment file:\n\n       ```bash\n       cp .env.example .env\n       ```\n\n   - Open `.env` and fill in your **Firebase** credentials and **NocoDB** tokens.\n   - Place your Firebase Service Account JSON file in the root directory (e.g., `service-account.json`).\n   - **Associate your Firebase Project**:\n\n       ```bash\n       firebase use --add\n       ```\n\n3. **Development Workflow**\n   This project uses a hybrid workflow: **Docker** handles the infrastructure (Database, NocoDB), while the **FinTrack App** runs locally on your machine for rapid development.\n\n   ### Step 1: Start Infrastructure \u0026 Setup Database\n\n   Spin up Postgres and NocoDB using Docker Compose:\n\n   ```bash\n   cd infrastructure/docker\n   docker-compose up -d\n   cd ../..\n   ```\n\n   - **NocoDB Dashboard:** [http://localhost:8080](http://localhost:8080)\n\n   #### 🗄️ Automatic Database Setup\n\n   Instead of creating tables manually, run the automated setup script. This will create all necessary tables, columns, and relationships in your NocoDB project.\n\n   1. Login to NocoDB and create a new **Project/Base** (e.g., \"FinTrack\").\n   2. Get your **API Token** (My Settings -\u003e API Tokens) and **Base ID** (Project Settings).\n   3. Update your `.env` file with `NOCODB_API_TOKEN` and `NOCODB_PROJECT_ID`.\n   4. Run the setup script from the root directory:\n\n       ```bash\n       pnpm run db:setup\n       ```\n\n       *Note: If the script detects existing tables, it will abort to prevent data loss. Use `pnpm run db:setup -- --force` to override this safeguard.*\n   5. The script will output the created **Table IDs**. Copy them into your `.env` file to finalize the configuration.\n\n   #### 🛠️ Development Utility Scripts\n\n   The following scripts are available in `backend/scripts/` to help with development and debugging:\n\n   - **Seed Data**: Populates your database with realistic dummy data for testing.\n\n     ```bash\n     pnpm run db:seed -- \u003cUSER_ID\u003e\n     ```\n\n   - **Check Data**: A diagnostic tool to verify the existence and integrity of a user's data.\n\n     ```bash\n     pnpm run db:check -- \u003cUSER_ID\u003e\n     ```\n\n   - **Email Diagnostic**: Interactively verify your SMTP configuration by sending a test email.\n\n     ```bash\n     pnpm run test:email\n     ```\n\n   ### Step 2: Start the Application\n\n   Run the frontend and backend locally from the root directory:\n\n   ```bash\n   # Install dependencies\n   pnpm install\n\n   # Development Mode (Hot Reload)\n   pnpm run dev\n   ```\n\n   - **FinTrack App:** [http://localhost:3000](http://localhost:3000)\n\n   \u003e **Note:** Ensure your `.env` file is configured with the correct `NOCODB_API_TOKEN` after you set up your NocoDB account in Step 1.\n\n   ### 🚀 Production Deployment\n\n   For production environments, the app is configured for process management via **PM2**. This ensures the application stays alive indefinitely and restarts automatically if it crashes.\n\n   **Run with PM2:**\n\n   ```bash\n   pnpm run pm2:start\n   ```\n\n   **Key Benefits:**\n   - **Process Monitoring**: Automatically restarts the server on crashes or system reboots.\n   - **Background Management**: Runs the application as a background daemon.\n   - **Log Management**: Centralized logs for both `stdout` and `stderr`.\n   - **Zero-Downtime Reload**: (Available via `pm2 reload`) for seamless updates.\n\n   *Note: Configuration is located in `infrastructure/ecosystem.config.js`.*\n\n## 📡 API Endpoints\n\nThe backend provides a RESTful API. Key endpoints include:\n\n- `GET /api/transactions` - Fetch transactions with filtering.\n- `POST /api/transactions` - Create a new transaction.\n- `GET /api/budgets/active` - Get currently active budgets.\n- `GET /api/subscriptions` - List all subscriptions and recurring payments.\n- `GET /api/cash-flow-forecast` - Get 30-day balance projection.\n\n*Full API documentation is available in the codebase under `backend/routes`.*\n\n## 🔧 Troubleshooting\n\n- **NocoDB Connection Failed:** Ensure the `nocodb-app` container is healthy (`docker ps`) and that your `.env` `NOCODB_API_URL` matches the Docker port (default 8080).\n- **Docker Paths:** All infrastructure files are located in `infrastructure/docker`. Commands should be run from that directory or use the absolute path.\n- **Firebase Errors:** specific `service-account.json` errors usually mean the file is missing or the path in `.env` is incorrect.\n- **Port Conflicts:** If port 3000 or 5432 is taken, update `infrastructure/docker/docker-compose.yml` or your local env.\n\n## 🤝 Contributing\n\nContributions are welcome! To ensure stability and high code quality, please follow these steps:\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/AmazingFeature`).\n3. **Lint-First Rule**: If your feature introduces a new language or framework, ensure its linter is configured and added to `pnpm run lint:all` before implementation.\n4. **Auto-Fix Rule**: Before manually addressing linting errors, always execute the project's auto-fixers to save time and tokens:\n\n    ```bash\n    pnpm exec eslint '**/*.{js,mjs,vue}' --fix\n    pnpm exec stylelint 'frontend/src/**/*.css' --fix\n    ```\n\n5. **Run local tests** to ensure no regressions:\n\n    ```bash\n    pnpm test          # Backend tests\n    pnpm run test:ui   # Frontend tests\n    pnpm run lint:all  # Code quality audit\n    ```\n\n6. Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`).\n7. Push to the branch (`git push origin feature/AmazingFeature`).\n8. Open a Pull Request.\n\n## 💎 Credits\n\nThis project was developed with the help of modern AI and design tools:\n\n- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)**: For autonomous coding, refactoring, and project management.\n- **[Google Stitch](https://stitch.withgoogle.com/)**: For visual design and UI components.\n\n## 📄 License\n\nThis project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniyazmft%2Ffinancial_tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniyazmft%2Ffinancial_tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniyazmft%2Ffinancial_tracker/lists"}