{"id":22449106,"url":"https://github.com/yrzito/expenseanalyzer","last_synced_at":"2026-05-03T19:33:06.232Z","repository":{"id":265177492,"uuid":"895362571","full_name":"YRZiTO/ExpenseAnalyzer","owner":"YRZiTO","description":"web-based application designed to help users track and manage their finances effectively.","archived":false,"fork":false,"pushed_at":"2024-12-18T14:25:19.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T12:14:34.362Z","etag":null,"topics":["budget-analysis","budgeting","expense-analyzer","expense-manager","expense-tracker","expenses","flask","personal-finance","python3"],"latest_commit_sha":null,"homepage":"http://ea.yousifzito.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YRZiTO.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}},"created_at":"2024-11-28T04:17:11.000Z","updated_at":"2024-12-18T14:25:25.000Z","dependencies_parsed_at":"2024-11-28T07:16:14.012Z","dependency_job_id":null,"html_url":"https://github.com/YRZiTO/ExpenseAnalyzer","commit_stats":null,"previous_names":["yrzito/expenseanalyzer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YRZiTO%2FExpenseAnalyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YRZiTO%2FExpenseAnalyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YRZiTO%2FExpenseAnalyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YRZiTO%2FExpenseAnalyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YRZiTO","download_url":"https://codeload.github.com/YRZiTO/ExpenseAnalyzer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245841762,"owners_count":20681195,"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","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":["budget-analysis","budgeting","expense-analyzer","expense-manager","expense-tracker","expenses","flask","personal-finance","python3"],"created_at":"2024-12-06T05:07:40.186Z","updated_at":"2026-05-03T19:33:06.188Z","avatar_url":"https://github.com/YRZiTO.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ExpenseAnalyzer\n\nExpenseAnalyzer is a web-based application designed to help users track and manage their finances effectively. Users can log expenses, set budgets, and monitor their financial health with real-time updates and insights. Key features include adding and categorizing expenses, setting monthly budget limits, receiving budget alerts, and performing real-time currency conversion using an integrated third-party API.\n\n## Features\n\n- Log and categorize expenses\n- Set and update monthly budget limits\n- Receive alerts when approaching or exceeding budget limits\n- Visual analytics for expense tracking and budget management\n- Real-time currency conversion using the ExchangeRate API\n\n## Technologies Used\n\n- Python (Flask) for the backend\n- SQLAlchemy for ORM and database management\n- Azure SQL Database for data storage\n- HTML/CSS for frontend design\n- ExchangeRate API for real-time currency conversion\n\n## Prerequisites\n\n- Python 3.10 or above\n- Virtual Environment (optional but recommended)\n\n## Getting Started\n\n### 1. Set up a Virtual Environment (optional but recommended)\n\n#### Using `venv`\n\n1. Create a virtual environment:\n\n   ```bash\n   python -m venv venv\n   ```\n\n2. Activate the virtual environment:\n\n   - On Windows:\n\n     ```bash\n     .\\venv\\Scripts\\activate\n     ```\n\n   - On macOS/Linux:\n\n     ```bash\n     source venv/bin/activate\n     ```\n\n### 3. Install Dependencies\n\nInstall the required packages listed in `requirements.txt`:\n\n```bash\npip install -r requirements.txt\n```\n\n### 4. Configure Environment Variables\n\n#### For Linux Users\n\nCreate a `configExpenseAnalyzer.json` file in the `/etc/` directory and add the following environment variables:\n\n```json\n{\n   \"SECRET_KEY\": \"your_secret_key\",\n   \"SQLALCHEMY_DATABASE_URI\": \"your_database_url\",\n   \"EMAIL_USER\": \"your_email\",\n   \"EMAIL_PASS\": \"your_email_app_password\",\n\t\"API_KEY\": \"your_exchangerate_api_key\"\n}\n```\n\n- Replace`your_secret_key`  with your Flask application's secret key for session management and security.\n- Replace`your_database_uri` with the database connection URI for your Azure SQL Database or SQLite. For SQLite, this might look like `sqlite:///path_to_db`.db.\n- Replace`your_email` and`your_email_password` with the email and app-specific password for the email service used to send notifications (e.g., Gmail, Outlook).\n- Replace`your_exchangerate_api_key` with your API key from the [ExchangeRate-API](https://www.exchangerate-api.com/).\n\n#### For Windows \n\nPlace the `configExpenseAnalyzer.json` file in the `instance` folder under the ExpenseAnalyzer directory. Ensure the application code references this path for Windows systems.\n\n### 5. Run the Application\n\nYou have two options to run the application:\n\n#### Option 1: Using `flask run`\n\n1. Set the Flask app environment variable:\n\n   ```bash\n   export FLASK_APP=run.py\n   ```\n\n   On Windows:\n\n   ```bash\n   set FLASK_APP=run.py\n   ```\n\n2. Run the application:\n\n   ```bash\n   flask run\n   ```\n\n#### Option 2: Using `python run.py`\n\nAlternatively, you can directly run the app by executing:\n\n```bash\npython3 run.py\n```\n\n### 6. Access the Application\n\nOpen your web browser and navigate to `http://127.0.0.1:5000` to access the ExpenseAnalyzer application.\n\n## Usage\n\n- **Add Expenses** : Navigate to the \"Add New Expense\" section to log expenses.\n- **Set Budget** : Set your monthly budget in the \"Set Budget\" section.\n- **Currency Conversion** : Use the currency conversion feature to perform real-time conversions.\n- **View Reports** : Access visual reports for monthly spending and category-based analysis.\n\n## Project Structure\n\nThe directory structure of the project is as follows:\n\n```text\nExpenseAnalyzer/\n|   requirements.txt          # Lists Python packages required to run the application\n|   run.py                    # Entry point for running the application\n|   README.md                 # Project documentation and instructions\n|\n+---instance                  # Folder for instance-specific configuration files\n|       configExpenseAnalyzer.json # JSON file for storing environment variables (not included in version control)\n|\n\\---app                       # Main application folder containing configurations, modules, and routes\n    |   config.py             # Configuration file for environment variables, database URI, and other settings\n    |   currency_loader.py    # Module to load currency data from the YAML file\n    |   extensions.py         # Initializes extensions like SQLAlchemy, Mail, Bcrypt, etc.\n    |   models.py             # Defines the database models (User, Expense, Budget) used in the app\n    |   multiton.py           # Implements Multiton pattern for managing unique instances of expense categories\n    |   observers.py          # Defines observer classes for handling notifications and logging (AlertObserver, LoggingObserver)\n    |   utils.py              # Utility functions for tasks like currency conversion, email sending, and data processing\n    |   __init__.py           # Initializes the Flask app and registers configurations and blueprints\n    |\n    +---api                   # Blueprint for API-related routes\n    |       routes.py         # Handles API routes for currency conversion and forecast\n    |\n    +---auth                  # Blueprint for authentication (user login, registration) routes\n    |       forms.py          # Defines authentication forms for user input\n    |       routes.py         # Manages routes for login, registration, and session handling\n    |\n    +---budget                # Blueprint for budget-related routes\n    |       routes.py         # Handles routes for setting, updating, and deleting budget limits\n    |\n    +---data                  # Folder for storing data files\n    |       currencies.yml    # YAML file containing country names and corresponding currency codes\n    |\n    +---expenses              # Blueprint for expense-related routes\n    |       routes.py         # Manages routes for adding, viewing, editing, and deleting expenses\n    |\n    +---factories             # Contains factory classes for object creation\n    |       expense_factory.py # Factory class to create Expense instances based on user input\n    |\n    +---main                  # Blueprint for main app routes (e.g., homepage)\n    |       routes.py         # Manages main routes like the home page\n    |\n    +---static                # Directory containing static assets for the application.\n    |       style.css         # Main stylesheet with custom CSS styles for ExpenseAnalyzer.\n    |       favicon.png       # Favicon icon displayed in the browser tab.\n    |       icon.128x128.png  # Shortcut icon for speed dial or bookmarks.\n    |       logo.512x512.png  # Logo image used on login and registration pages.\n    |\n    |   +---js                # Directory for JavaScript files within static assets.\n    |       interaction_handler.js  # JavaScript for handling flash message animations, form submissions, and preventing duplicate submissions.\n    |\n    \\---templates             # Folder containing HTML templates for the app\n            add_expense.html      # Template for adding a new expense\n            base.html             # Base template with shared layout elements\n            edit_expense.html     # Template for editing an existing expense\n            login.html            # Template for user login page\n            register.html         # Template for user registration page\n            set_budget.html       # Template for setting a new budget\n            update_budget.html    # Template for updating an existing budget\n            view_expenses.html    # Template for viewing and managing expenses\n```\n\n## Design Patterns\n\nExpenseAnalyzer leverages several design patterns to improve maintainability and scalability:\n\n- Factory Pattern in `ExpenseFactory`: Used to create expense instances efficiently.\n- Singleton Pattern in `BudgetSingleton`: Ensures a single source of truth for budget management.\n- Observer Pattern with `AlertObserver` and `LoggingObserver` in `observers.py`: Handles alerts and logs actions when budget thresholds are reached or exceeded.\n- Multiton Pattern in `ExpenseCategoryMultiton`: Maintains consistency across expense categories.\n\n## License\n\nThis project is licensed under the GPL-3.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyrzito%2Fexpenseanalyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyrzito%2Fexpenseanalyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyrzito%2Fexpenseanalyzer/lists"}