💸 guitos

<details> <summary>Table of Contents</summary>

• About
• Published On
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Notes
• AI Analysis
• Known issues
• Container
• Docker compose
• Related Projects
• Built With
• Hosted On
• Roadmap
• Support
• Contributing
• Authors & contributors
• Security
• License
• Acknowledgements

</details>

| Horizontal layout | Vertical layout | | :--------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------: | | <img alt="guitos horizontal layout screenshot" src="docs/images/horizontal.png" title="Horizontal" width="100%"> | <img alt="guitos vertical layout screenshot" src="docs/images/vertical.png" title="Vertical" width="100%"> |

<details> <summary>Additional screenshots</summary> <br>

| Light theme | Light theme | | :--------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------: | | <img alt="guitos light theme horizontal layout screenshot" src="docs/images/horizontal-light.png" title="Horizontal light" width="100%"> | <img alt="guitos light theme vertical layout screenshot" src="docs/images/vertical-light.png" title="Vertical light" width="100%"> |

| History | Initial state | | :----------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------: | | <img alt="guitos history screenshot" src="docs/images/history.png" title="Tooltip" width="100%"> | <img alt="guitos initial state screenshot" src="docs/images/initial-state-vertical.png" title="Initial state" width="100%"> |

| Charts | Charts light theme | | :---------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------: | | <img alt="guitos charts page screenshot" src="docs/images/vertical-charts.png" title="Charts" width="100%"> | <img alt="guitos light theme charts page screenshot" src="docs/images/vertical-charts-light.png" title="Light theme" width="100%"> |

</details>

About

guitos is a personal budgeting app that helps you figure out where your money went, plan your budget ahead of time and analyze past expenditures.

It stores data in your browser's local storage (IndexedDB). Your private financial data doesn't leave your browser.

guitos was initially created to replace a spreadsheet and as an opportunity to learn React.

guitos is portuguese slang for money/cash.

Published On

• Show HN
• producthunt.com
• store.app
• r/SideProject
• r/reactjs
• r/selfhosted
• selfh.st

Getting Started

Prerequisites

1. Any modern browser with javascript enabled.

Installation

It's not necessary to install anything in order to use this app.

However, if you'd like to use it offline, follow the instructions for your device on: web.dev or use the container image

Usage

Use case example

I receive a salary at the end of each month and around that time I create a new budget to plan the expenses/savings goals/etc.

I frequently add a new expense before I purchase it so I can see the impact on the budget and prepare accordingly. If everything went according to plan, once I receive a new salary, I transfer the value in the savings estimate field to my bank savings account.

Later, I can compare the budget with previous months to understand where the money is going by hovering the mouse/tapping on a single expense. A tooltip pops up and shows its value in percentage of revenue (see the tooltip screenshot above). The charts page is useful for these kinds of insights.

There I can see an overview of the evolution of several metrics such as savings, revenue, etc. If I want to narrow down the chart to a specific type of item I can search for it in the filter searchbox. If I toggle the strict match button then only items that are named exactly as the search value are shown in the resulting chart.

Starting from scratch

1. Visit guitos.app
2. Create a new budget and name it according to your preferred budget period
   • ideally in one of the following formats: YYYY-MM or YYYY-WN
3. Input your revenue for the respective period (salary, sales, etc.)
4. Fill in the expenses (groceries, electricity, etc.)
5. Change the savings goal to your preference
6. Update the reserves field with the current value of your emergency fund / cash

In case you have a backup/would like to import data from another source

1. Visit guitos.app
2. Import data from single/multiple CSV files or a single JSON file. Make sure they follow the required structure:

CSV data model

type,name,value
expense,rent,1000.00
expense,food,200.00
income,salary,2000.00
income,sale,100
goal,goal,10
reserves,reserves,0

• Note that the name of the CSV file is parsed as the name of the budget:

  2023-04.csv results in a budget with the name of 2023-04.

JSON data model

[
  {
    "id": "035c2de4-00a4-403c-8f0e-f81339be9a4e",
    "name": "2023-03",
    "expenses": {
      "items": [
        { "id": 1, "name": "expense1", "value": 10 },
        { "id": 2, "name": "expense2", "value": 20 }
      ],
      "total": 30
    },
    "incomes": {
      "items": [
        { "id": 1, "name": "income1", "value": 100 },
        { "id": 2, "name": "income2", "value": 200 }
      ],
      "total": 300
    },
    "stats": {
      "available": 270,
      "withGoal": 240,
      "saved": 270,
      "goal": 10,
      "reserves": 100
    }
  }
]

• Note that the ID of each budget inside the JSON file should be a v4 UUID as created by the crypto.randomUUID() method.

Keyboard shortcuts

Keyboard shortcuts can be triggered when no input field is selected.

| Action | Shortcut | | --------------------------------- | -------- | | Undo last change | U | | Redo last change | R | | Clone current budget | C | | Create new budget | A | | Open import/export panel | O | | Export data as JSON | S | | Export current budget as CSV | D | | Export data as AI friendly prompt | H | | Open settings panel | T | | Go to older budget | PageDown | | Go to current month's budget | Home | | Go to newer budget | PageUp | | Rename current budget | N | | Search | F or / | | Focus savings goal | G | | Focus reserves | E | | Toggle charts view | I | | Dismiss all notifications | Escape |

Notes

• The undo/redo functionality cannot fix every single action. Export frequently to avoid data loss!
• To undo the deletion of a budget click the undo button in the notification shown just after the action.
  • As soon as the notification fades (after 60 seconds) the undo action is not possible anymore.
• guitos tries to load an existing budget when visiting guitos.app/budget-name
  • it will also try to load the budget that was last visited if none is specified in the URL
• The interface theme is set automatically by your browser and/or operating system's configuration.
• The currency is initially selected according to your browser's preferred languages.
  • Example: English (United States) browser language displays values in US Dollars. English (India) uses Indian Rupees.
  • It's