💸 guitos

Table of Contents

• About
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Notes
• Built With
• Hosted On
• Roadmap
• Support
• Project assistance
• Contributing
• Authors & contributors
• Security
• License
• Acknowledgements

Screenshots

Horizontal layout	Vertical layout

Light theme	Light theme

Tooltip	Initial state

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.

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

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 a 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).

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

Keyboard shortcuts:

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

Action	Shortcut
Clone current budget	C
Create new budget	A
Export data	S
Go to older budget	PageDown
Go to newer budget	PageUp
Rename current budget	R
Search budget list	F or /
Focus savings goal	G
Focus reserves	E

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.

Notes

• There is no undo/redo functionality. Export frequently to avoid data loss!
  • This is planned to be implemented on #16
• guitos uses floating point math so it can be inaccurate due to rounding errors.
  • There are plans to improve accuracy on #19
• guitos tries to load an existing budget when visiting guitos.app/budget-name
• The interface theme is set automatically by your browser and/or operating system's configuration.
• The currency is formatted according to your browser's preferred languages.
  • Example: English (United States) browser language displays values in US Dollars. English (India) uses Indian Rupees.

Built With

• React
• Bootstrap
• React Bootstrap
• React Bootstrap Typeahead
• React Icons
• React Router
• React Currency Input Field
• React Hotkeys Hook
• Dinero.js
• localForage
• PapaParse
• Vite
• Typescript
• Dracula
• Dracula.min Light

Hosted On

• Cloudflare Pages

Roadmap

See the open issues for a list of proposed features (and known issues).

Support

Reach out to the maintainer at one of the following places:

• GitHub issues
• Contact options listed on this GitHub profile

Project assistance

If you want to say thank you or/and support active development of guitos:

• Add a GitHub Star to the project.
• Write interesting articles about the project on your personal blog.

Together, we can make guitos better!

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Authors & contributors

The original setup of this repository is by Nuno.

For a full list of all authors and contributors, see the contributors page.

Security

guitos follows good practices of security, but 100% security cannot be assured. guitos is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the GNU Affero General Public License v3.

See LICENSE for more information.

Acknowledgements

• r/personalfinance
• Eslint
• Prettier
• Choose a license
• Hands on React