firefly-iii/firefly-iii

Firefly III: a personal finances manager

Firefly III

A free and open source personal finance manager
Explore the documentation

View the demo · Report a bug · Request a feature · Ask questions

• About Firefly III
  • Purpose
• Features
• Who's it for?
• The Firefly III eco-system
• Getting Started
• Contributing
• Support the development of Firefly III
• License
• Do you need help, or do you want to get in touch?
• Acknowledgements

About Firefly III

"Firefly III" is a (self-hosted) manager for your personal finances. It can help you keep track of your expenses and income, so you can spend less and save more. Firefly III supports the use of budgets, categories and tags. Using a bunch of external tools, you can import data. It also has many neat financial reports available.

Firefly III should give you insight into and control over your finances. Money should be useful, not scary. You should be able to see where it is going, to feel your expenses and to... wow, I'm going overboard with this aren't I?

But you get the idea: this is your money. These are your expenses. Stop them from controlling you. I built this tool because I started to dislike money. Having money, not having money, paying bills with money, you get the idea. But no more. I want to feel "safe", whatever my balance is. And I hope this tool can help you. I know it helps me.

Purpose

Personal financial management is pretty difficult, and everybody has their own approach to it. Some people make budgets, other people limit their cashflow by throwing away their credit cards, others try to increase their current cashflow. There are tons of ways to save and earn money. Firefly III works on the principle that if you know where your money is going, you can stop it from going there.

By keeping track of your expenses and your income you can budget accordingly and save money. Stop living from paycheck to paycheck but give yourself the financial wiggle room you need.

You can read more about the purpose of Firefly III in the documentation.

Features

Firefly III is pretty feature packed. Some important stuff first:

• It is completely self-hosted and isolated, and will never contact external servers until you explicitly tell it to.
• It features a REST JSON API that covers almost every part of Firefly III.

The most exciting features are:

• Create recurring transactions to manage your money.
• Rule based transaction handling with the ability to create your own rules.

Then the things that make you go "yeah OK, makes sense".

• A double-entry bookkeeping system.
• Save towards a goal using piggy banks.
• View income and expense reports.

And the things you would hope for but not expect:

• 2 factor authentication for extra security 🔒.
• Supports any currency you want.
• There is a Docker image.

And to organise everything:

• Clear views that should show you how you're doing.
• Easy navigation through your records.
• Lots of charts because we all love them.

Many more features are listed in the documentation.

Who's it for?

This application is for people who want to track their finances, keep an eye on their money without having to upload their financial records to the cloud. You're a bit tech-savvy, you like open source software and you don't mind tinkering with (self-hosted) servers.

The Firefly III eco-system

Several users have built pretty awesome stuff around the Firefly III API. Check out these tools in the documentation.

Getting Started

There are many ways to run Firefly III

1. There is a demo site with an example financial administration already present.
2. You can install it on your server.
3. You can run it using Docker.
4. You can deploy via Kubernetes.
5. You can install it using Softaculous.
6. You can install it using AMPPS.
7. You can install it on Cloudron.
8. You can install it on Lando.
9. You can install it on Yunohost.

Contributing

You can contact me at [email protected], you may open an issue in the main repository or contact me through gitter and Mastodon.

Of course, there are some contributing guidelines and a code of conduct, which I invite you to check out.

I can always use your help squashing bugs, thinking about new features or translating Firefly III into other languages.

Sonarcloud scans the code of Firefly III. If you want to help improve Firefly III, check out the latest reports and take your pick!

There is also a security policy.

Support the development of Firefly III

If you like Firefly III and if it helps you save lots of money, why not send me a dime for every dollar saved! 🥳

OK that was a joke. If you feel Firefly III made your life better, please consider contributing as a sponsor. Please check out my Patreon and GitHub Sponsors page for more information. You can also buy me a ☕️ coffee at ko-fi.com. Thank you for your consideration.

License

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

Do you need help, or do you want to get in touch?

Do you want to contact me? You can email me at [email protected] or get in touch through one of the following support channels:

• GitHub Discussions for questions and support
• Gitter.im for a good chat and a quick answer
• GitHub Issues for bugs and issues
• Mastodon for news and updates

Acknowledgements

Over time, many people have contributed to Firefly III. I'm grateful for their support and code contributions.

The Firefly III logo is made by the excellent Cherie Woo.

firefly-iii's Issues

Double check create new deposit form.

Implement hack / program in hack / use hhvm

Just as an experiment, see where it gets me. It might be cool!

Split piggy banks and repeated expenses

Double check create new transfer form.

Breadcrumbs

Everywhere!

Better chart for account overview + data tables

The current view doesn't allow for easy date navigation, unless we expand the chart and make it leading. That means also need to use some kind of data table.

A button to create new budgets

With a pop up form on pages where a budget can be selected. Would refresh the parent page.

Expand category view.

The current category view contains text akin to "todo" which of course is a bit weird

Reminders when piggy bank is full or fuller than expected

They should correct for this and remind about a smaller amount or not remind at all.

Cache account balances.

With each new transaction, balances all over the place get updated. At the moment, everything is done live. It might be worth my time to see if we can cache this somehow. So far, this has been more trouble than it's been worth. Getting an account balance is a simple sum and not that expensive.

Date indicator on home screen

With the new view, the home page needs a clear indicator of the displayed date range.

Implement integration and unit tests for new code (see #25)

This might be relevant when fixing things using the brand new git flow I'm using.

Think again about CRUDv

Alright the CRUDv thing I thought of might not work, because even though CUDv is OK, the R for read isn't. The problem is that every model has different read-actions. All accounts, all accounts by a certain account_type, all budgets by a date limit which is inside a repetition.. bla bla bla.

So, I was thinking about multiple interfaces for sure, where a class might implement CUDv (not a good name but OK), and specialized Account / Budget interfaces that provide the methods required. Or maybe even something with traits and functions and so on; it's just that I don't know exactly how that works. Yet.

Relate transactions, but better

The basics are up for now but the code is sloppy and the process confusing.

Reset / verification do the same thing

Namely:

-make code, save

• Mail user.
• Ask to click link
• reset code
• send password

This feature could be fixed with using different mail templates and/or routes.

Remove magic number

There's a magic number in a complex query in FireflyIII\Database\Account\Account::destroy

Some thoughts

Alright so here's the problem.

Sooner or later everything touches everything. Ew! There's transactions and journals and budgets and accounts and just about every single view has a different set of requirements. Some only need transactions, others only need budgets but sooner or later there's a search for the related journal or the transactions in a budget and then it's all back to square one: a single method is "including" a billion tables methods and resources.

Firefly can go about this two ways. Either it keeps everything ready just in case the current method requires it, or it does everything on the fly. Another, the current solution is to include stuff when we need it through helpers, which keeps the code fairly clean but passes of the problem to various helpers, builders, implementers and factories.

It's pretty difficult to find out what's needed because the application is growing and changing all the time. A 'service'-kind of a situation could catch some problems but in the end it's all down to App::make a billion things and just run with it. Services that "do exactly x" quickly overflow because every method needs a tiny thing done differently which ends with twenty thousand methods all doing things slightly differently.

So then. Maybe some rules and regulations to get this thing going? Throwing around the core ideas behind Firefly III all the time isn't working either. And the tests! The tests!

Grouping stuff within their respective controllers isn't working because give me five seconds before I come up with some kind of combined view that messes everything up.

Same with helpers. It's nice, moving code around, pushing it towards these helpers but sooner or later the same problem arises; it becomes a mess.

Oh and then there's the problem of combining views with JSON which often means I'm picking up the same things twice, writing code twice. It sucks.

And if I decide to make objects as inclusive as possible I'm also back to square one where showing a budget generates 50 billion queries "just in case".

It all starts so simple but it becomes a giant mess. I think I need to draw something.

Migrate from Firefly Mark II to Firefly Mark III

Is possible automatically migrate the database from Firefly Mark II to Firefly Mark III?

Rename recurring transactions to bills

I can't believ I didn't think of this sooner

Form submit and methods

Always through post.

Use object binding for edit and delete! Aka fix everything. Also make sure to catch all errors.

Fix a "no budget / no category" view.

Account meta data

With the idea of giving accounts more information than just a name, there's a new table and dito coupling for account 'roles', ie. roles for shared accounts, roles for expense accounts, etc. These roles should be expanded in the future to keep track of debet / credit cards, debts and other things.

Since both the name and format of account meta information is completely free-form there should be some kind of documentation / information and maybe some kind of check to see if meta information is valid.

On the other hand, since the account meta fields are currently used for nothing more than 'shared accounts' vs. 'normal accounts', it may be easier to simply drop the whole thing and say shared=1 / shared=0 in one of the account table fields.

Calculated costs

When having (large) costs, for example paying car taxes once a year, it would be nice to see how much of the monthly budget this will take. And thus how mush money we would need to set aside each month to cover the complete cost.

Another example could be: I want to buy a new smartphone every 3 years, how much money do I need to set aside each month to cover this cost.

This way you also have a "general" usage that should be the same every month and should allow you to pay for every (big) costs.

The bills-view needs a menu in the title-bar

This menu should contain "create new bill".

Notes for tests

View

• Is the right view being called.
• Are the arguments for the view present and correct?
  -- Check at least the name of the view

Redirect

• Redirect route matches expected?
• Redirect status / OK status matches?

General

• All cases covered?
• Different test cases to see those differences (aka not just watching for the same redirect event, check where the redirect goes to).

Budget report

I've removed the budget report for now because the code sucks. Here's the general idea:

Every month I set budgets, totalling 1000,-. My balance for that month on my checking account is 1000,- as well.

While spending money, moving money etc., the amount left in the checking account should match what I've spend that month. Ie. spent 400, balance must be 600.

If this is not the case, one of a few things may have happened:

• Other accounts have joined the spending frenzy. Credit card expenses are part of the budgets as well, but my main account moves away from the balance it should have. If I spend 400 on my main, and 100 on my CC, the "total balance left" is 500, but the main says it's 600.
• Transfers that are not accounted for.

So a budget-report should show:

• The total amount budgeted for that month.
• The amount of money spent within budgets.
• Whether or not this matches the amount of money spent on all of my accounts
• Whether or not there is money "missing".

spentInRepetition() should be moved

It's now part of the LimitRepetition model but rather it should be somewhere in a helper or in a repository.

Views for piggy banks / repeated are exactly the same.

So is code in backend.

Switch to Google charts

Highcharts is pretty slow and misses some diagrams I need.

On the backend, this means changing a lot of JSON to be compatible with Google. We'll concentrate this code effort into /Firefly/Charts/SimpleCharts(Interface) and maybe more classes + a controller called ChartController so we may switch back easier.

On the front end each page with a chart should be able to point to the source URI (defined using Laravel's route()) and the target-container so only one function needs to be called & implemented.

This also calls for a new asset manager but we'll see.

Double check create new expense form.

Recurring transactions monthly overview

It would be nice to have an overview of all recurring transactions, grouped by month.
This way we know what the total expected cost will be for that month.

Based on the total amount for a month we could divide the months into groups, or add labels to them, like "easy month", "normal month", "hard month". (based on the largest amount and smallest amount)

This way it will be easy to see that (for example) next month will be hard (electricity, water, paying taxes, insurance,...) but the month after that will be easy (only electricity). So if we want to do something extra, we better wait until the easy month.

Allow users to create transactions with other currencies

In several places EUR is now the hard-coded default. Should be fixed with a dropdown and a select thing and what-not.

Migration issue

I've just migrated from the last tag and I get the following error when I browse to the dashboard:

production.ERROR: exception 'InvalidArgumentException' with message 'View [transactions.journals-small-index] not found

I've run the migrate command, flushed the cache and dump-autoloader.
But nothing helps.

currentRelevantRep should be moved

It's a useful little method but it should be moved to a static library or somewhere else.

Remember controllers

Controllers should only re-format data, not get extra data, update fields, whatever.

Icons for titles

See title.

Unify datatables.

Each datatable so far is a mix of options, calls to Firefly, and the backend is quite messy as well. It's all unified into the Json helpers which is not that good. To properly fix these, I should build:

• A backend datatables controller that can generate the proper lists of data (accounts, transactions, etcetera)
• Frontend thing that can properly call the proper URL and format data.

Bills > Bill in the menu.

Two bugs

1. Edit recurring transaction does not work when you remove active/automatch.
2. Budget select list is broken in edit transaction.

Still need a nice view for piggy bank / repeated expense.

Inconsistent titles, icons and code.

Some views use View::share. Others use ->with(), and none of them are the same. Also consolidate title and subtitle use.

Opening balance

The relation between an account and its opening balance is a bit weird. The system creates a super special transaction with a super special opposing account to "fill" (positive or negative) the user's account with its initial balance. Neither the account nor the transaction are directly editable but rather when you edit or create a new account a whole range of code gets set in motion to create a new (super special) transaction and a new (super special) account just to get the initial balance right.

Even though this initial balance thing is technically correct, the code is sloppy and confusing.

• Make a "normal" expense and "normal" revenue account called "Unknown / existing source" from which the money will be drawn (or into which the money will be put).
• Make a normal transaction for the opening balance, no weird stuff with "opening balance transaction types". This makes the opening balance editable.
• Make sure the system has some sort of fallback for the user to explain how this works. Aka. more help and wizard-pages.

Piggy bank reminders and information

There's a lot to be done for piggy banks, which (when reminders are set) doesn't accurately show how much money is due, when it's due, etc etc.

Support for variable currencies.

Contact me!

JC5, Id like to talk to you about this project. Im working on something similar, but it only handles stocks. Id like to see if you and i can help each other out.

you can take a look at my work at http://dev.pureintellect.com and email me at [email protected]

Dropdowns should have a button "create new X"

Some fields are freeform, which makes it possible to create new expense accounts on the fly. Some fields are dropdowns and this makes it impossible to do the same. Instead, a small button (+) should be provided so users can create a new thing (whatever it might be).

Configurable budget max limit

There is a max limit to the budget amount, its 900 (euro). Its too few some currency especiel HUF. It should be useful if this value will be configurable.

Action button on dashboard

To create new withdrawal/expense/things

Cannot make accounts active / inactive.

Note to self: form layout

• Mandatory fields on the left, optional on the right (col-lg-6)
• Title contains "Firefly", and a short string describing the action "edit account"
• Title contains only the basics. Edit. Remove. Delete. Etc.
• Lead paragraph contains details, explanation (help).
• Then extra text, class "text-info"
• Fields have "help-block" text if need be.
• Failed submits always give back feedback.