New App: HLedger Plain Text Accounting

💻 Development app dev
1

I’m working on a new app and am looking for people interested in contributing or participating/providing feedback. Let me know if you’re interested!

HLedger Plain Text Accounting on Nextcloud

HLedger is cross-platform accounting software for both power users and folks new to accounting. It’s good for tracking money, time, investments, cryptocurrencies, inventory and more.

Plain Text Accounting means doing accounting with plain text data formats and scriptable software.

Why Plain Text Accounting on Nextcloud?

Rather than storing financial data in a rigid or proprietary database, you can just record all your transactions as text and let the reporting tools do the hard work.

As a file storage system with desktop sync and mobile access, Nextcloud is a natural fit for plain text accounting. It provides a safe, private, easily accessible place to store your financial data. It provides security, online editing, multi-user, collaboration, desktop sync and mobile device access without compromising privacy or forcing you to trust a company as you must do with tools like Quicken, Mint, YNAB, etc…

Screenshots

Income Statement
Income Statement2318×2012

Balance Sheet
Balance Sheet2318×2012

Files

Interested?

This project is just getting started. If you’d like to participate, post in Nextcloud App Dev or message me directly.

3 Likes
2

Ok, so I am an accountant (Canada), and I also have a master’s degree in computer engineering and worked in that field for several years before switching to accounting.

I think its a brilliant idea to bring accounting to Nextcloud. I agree that it is a perfect fit.
HOWEVER, I think the idea of using plain text files for the database is a non-starter. Right off the bat, you’re making certain that you are limiting the scope of what you can accomplish.

You don’t seem to be providing an adequate argument against using a database. I agree that a proprietary database is terrible and frustrating, but a well defined and documented OPEN database would be very helpful. As for a database being rigid, well naturally. As your text file must be as well in order to reliably read and use it. The rigidity isn’t a weakness, it is a guarantee that relationships will be maintained without failure – this will ensure that your data isn’t destroyed.

Now of course, I’m all for being able to EXPORT the data in the database into a plain text file. That is actually a useful feature that allows the data to be shared with your accountant, who more often than not doesn’t use the same software as you do :slight_smile:

The bottom line is this; what you are proposing boils down to actually building your own relational database using text files as the data storage back end. All data in any relational database can be represented in that way already, think CSV files. Any table can be exported in its entirety to a CSV file. So the question then is this; if that is the case, then WHY do we bother with database servers like MariaDB with binary table formats like InnoDB? The answer is complex, but some of the reasons are these;

  1. indexes help with data access performance – rather than having to search manually through a huge text file, we can use shortcuts to get to the data we need quickly.
  2. multiple users can share a single database when arbitration is provided by a database server. This is something you can’t safely do with text files, if you have 2 users in the text file at the same time, whichever user saves the file LAST wins, whereas the database server will ensure that transactions are entered into the database in order and without obliterating prior entries.
  3. the database guarantees correct data types in all columns, you can’t accidentally put a string into an integer column. It also guarantees that the values entered are reasonable for the context, and that you don’t miss required columns.
  4. databases allow you to perform complex queries with ease, such as joining tables and restricting results. I can’t even describe how complicated that would be to replicate with plain text.

I’ll give you a really simple example of number 2 killing your data; say you have your plain text database file located in a group folder, and 4 members of your bookkeeping/accounting staff have access to it. George is entering a purchase of $10,000 worth of raw materials for the manufacturing of widgets, and Gracie is entering a sale of 5,000 widgets at $10 each. Because it is a plain text file, they both have the file loaded into memory at the same time. First George enters the purchase transaction and saves the file, then Gracie enters the sales transaction and saves the file again. Because the file was in Gracie’s memory, and that memory didn’t include George’s purchase transaction, as soon as Gracie hits the save button, George’s transaction is basically DELETED. That’s not something you want to have happening to your precious accounting data, and is probably the MOST IMPORTANT reason why accounting data MUST be stored using a transactional database.

Now remember, if you want to be able to access your stored data as a plain text file, all you need is to have an export button that select’s all data from the database and writes it to a plain text file, and there is no limit to the formats you can export it in, so there is no risk of loosing touch with your data.

I would be thrilled to participate in this project, but if I am going to, then it absolutely has to become something that I can recommend to my own clients, or maybe even offer the service to my clients using my own server.

1 Like
3

Thanks for the well reasoned and thorough reply! I don’t disagree with you on most of the points you made. I’m not an accountant. I use plain text accounting for my own personal accounting. My business accounting is currently on QBO because that’s what my accountant uses.

My goal in this app isn’t to build the ideal commercial accounting system in Nextcloud, it’s that I (and many others) already use plain text accounting and like it very much. I would like to make more accessible and easier to use, for me and for those who don’t use command line all the time. It may only be a fit for personal and small business accounting, I honestly don’t know, I’m not a professional accountant. But the existence of this app wouldn’t prevent another accounting app from being developed in Nextcloud.

I would have to defer to the plain text accounting people on the merits of it. I just know it’s worked very well for me.

What and Why?

What are the advantages over traditional (Free/open-source) accounting software, like GnuCash?

  • The data is more future proof. You can access it relatively easily with different software, newly-written software, or no software.
  • The command-line based UI, together with the plain text format, allows easy integration with other software (such as Nextcloud!), custom workflows and automation.
  • The user’s responsibilities and mental model feel simpler, ie: “I just need to keep a list of transactions”. Complex features and tools are not visible until you need them. Common actions can be easily scripted for daily use.
  • The data can be managed using the rich ecosystem of tools for managing text.
  • Most significantly, the data can be effectively version controlled, providing an audit trail, unlimited “undo”, and collaboration.
  • Because the software (mostly) does not touch your data, and because version control would let you know and roll back if it did, you can have great confidence in the integrity of your data. If the software misbehaves, your data is not at risk.
  • The data/tool separation facilitates decentralized development, stimulating an ecosystem of more tools and integrations.

What are the advantages over commercial accounting software, like QuickBooks?

In addition to the advantages above, being Free or Open Source software helps ensure: - No lockin - your data remains accessible, and there are no yearly fees. - You can fix, enhance and port the software. - The software is more portable, scriptable, and lightweight.

Objections and Concerns

Isn’t a plain text format too limited for large organizations?

“it’s pretty obvious that plain-text files don’t scale to a multinational, with hundreds of accountants of various types all trying to work with the same files. Even with proper use of Git I bet that would get old fast. You would instead want a real database, with a schema, and some data validation and some programs/webpages to smooth out the data entry and querying and whatnot.”

I’m not sure. Current plain text accounting tools can do some schema definition and data validation, and will do more in future. The plain text storage format is open, human-readable, future-proof (useful even without the software), scales smoothly from simple to complex needs, and taps a huge ecosystem of highly useful tooling, such as version control systems. And, despite the name, there’s no reason these tools can’t support other kinds of storage, such as a database.

4

Oh, I didn’t realize that this was using 3rd party software. Good luck then, but PLEASE be careful to make sure that you don’t end up with people thinking it would be ok for multiple users to access just because its accessible on a multi-user platform.

5

One of the benefits of using text is the journal/transaction files work with version control systems such as git to enable multi-user collaboration, rollback, and change tracking. My hope is to use the collaborative editing and built-in version control in Nextcloud for safe multi-user access. It works with plain text as well as markdown.

6

Databases don’t need to be “shared” with version control since the database server inherently supports multi-user collaboration – you don’t need weird hacks like git. On top of that, financial data should NOT be rolled back. If errors are made, they should be corrected with a correcting journal entry.

And as I’ve already described, version control WILL NOT support multi-user access anyway, since the two users in the example I gave you would either be making their changes prior to the file being committed to git, or if they are working with separate forks, then there will likely end up being a merge conflict. This text file is a BAD approach and will NEVER be safe in a multi-user environment unless you create a transaction arbiter, and to do that would require a separate server process – you would effectively have to write a database server.

1 Like
7

hledger author here, pardon my butting in. We had hledger packaged for Sandstorm, and we’d love to have it easily available for Nextcloud users too. Plain text accounting has its own strengths, and a good-sized community of happy users who find it useful. This proposed app doesn’t preclude other kinds of accounting apps on Nextcloud.

I expect there are plenty of details to work out about which interaction modes to expose (text file edit, text file append, web ui edit, web ui append…) and how to manage and communicate that. Larry_Boyd’s warnings will be useful for that part I expect.

https://hledger.org
https://plaintextaccounting.org

2 Likes
8

Git doesn’t help when multiple users are editing the same copy but I’m hoping Nextcloud’s collaborative editing and version control will. It should be like collaborating in Google Docs or O365.

9

It won’t and can’t.
Nextcloud version control just keeps some backups (and deletes some based on an algorithm described in the supporting pages for it). It doesn’t change the contents of the file that is on top and it while it may provide a backup of George’s (from the example I gave) input, those changes will STILL be overwritten by Gracie – not merged.

As for the supposed collaborative editing features, those features and capabilities involve the DATABASE. Access to file-based data storage on Nextcloud is NO DIFFERENT than two people sharing a path on a network filesystem, which are notorious for having one person’s changes being removed by a subsequent save of the file by someone else. THIS IS PART OF THE REASON DATABASES EXIST!

10

If it helps ease your concerns, I was a professional software engineer in my past career, like you. I’m familiar with the problems and solutions around synchronization, race conditions, atomic operations, transactions etc… I’ll definitely take this seriously and appreciate your concern.

I’m confident that we can do it safely. If it turns out Nextcloud collaborative editing is insufficient then we won’t use it. As @simonmichael suggested, we could limit editing to a web UI that just appends to the journal file. It doesn’t matter what order transactions are entered in HLedger so this can easily be done safely. Likewise, if Nextcloud’s version control is insufficient then we could integrate another version control system into the app.

I still believe collaborative editing is worth investigating…

Nextcloud introduces collaborative rich text editor

To illustrate where Nextcloud Text takes you, let’s describe a possible meeting you’ll have one day.

You have shared the meeting notes template in advance with all members. It has a basic structure, making sure nothing gets missed.

During the meeting, one person is dedicated note takers, while the others should check and make sure the notes are correct. As two members couldn’t make it, a call is started (conveniently in the side bar) while chat is used to coordinate.

Nextcloud Text

  • Work together: Share and collaborate with friends and colleagues, no matter if they use Nextcloud or not!
  • Strong foundation: We use :cat2: tiptap which is based on :owl: ProseMirror – huge thanks to them!

ProseMirror Collaborative editing

ProseMirror has built-in, ground-up, rock solid support for collaborative editing, where multiple people work on the same document in real time.

11

I can understand @Larry_Boyd concerns. I am tax consultant and it feels strange to use a text file for this.

But anyway, very interesting to have this progress in NC.

I am not a programmer. But if you want some knowledge from Germany or a bit from Europe, feel free to ask me.

Is it possible to increase the functions? I am looking for an option to be able to write invoices via NC.

Another point: Cryptocurrencies. There is a lot of software outside, which is not covering the needs of a company (!) which is working with cryptos. In Germany we have cointracking or cryptotax. But they can’t make the difference between trading token (VATfree) or income paid in token.

How difficult it would be, to increase the function of this bookkeeping?

1 Like
12

I am tax consultant and it feels strange to use a text file for this.

I can imagine it would! For me, the biggest obstacle to staying on top of my personal finances was data entry, because it takes my valuable time and with tools like GnuCash I always fell off the wagon. Plain text accounting has helped solved that problem for me because I find it really easy to enter transactions from multiple tools. I find bookkeeping with HLedger much easier than when I do it for my business in Quickbooks Online.

if you want some knowledge from Germany or a bit from Europe, feel free to ask me.

Thanks!

I am looking for an option to be able to write invoices via NC.

I haven’t tried invoicing with HLedger but here is the documentation for it. If HLedger supports it then we can add it to this app but I have no idea how good the invoicing feature is.

Cryptocurrencies. There is a lot of software outside, which is not covering the needs of a company (!) which is working with cryptos.

Hledger supports multiple currencies. Here’s an example with a cryptocurrency. If HLedger supports it then I suspect we can add it to this app.

13

GnuCash was really horrible, when I was working with it (15 years ago). Booking was made in branches. So when I want to book a transaction I had to click through everything first.

This helps beginners of course but it is wasting so much time.

This is great! I am booking with DATEV Software und Consulting

But they still not support cryptocurrencies.

Looks like this is easy possible with hledger.

I found this:

for German accounting (unfortunately it is SKR04)

and this:

for VAT.

As I understand, all bookkeeping is in a file. So it would be possible to store this easy via github and stay compliant to the German GoBD.

Another point: is it possible to add a hyperlink or so to the transaction? Because then you could add an invoice to the transaction (pdf or so). This invoice will be stored in NC.

14

is it possible to add a hyperlink or so to the transaction? Because then you could add an invoice to the transaction (pdf or so).

I think you could add the hyperlink in the transaction comment. I’m treating this app as an easy way to access hledger functionality but hledger will remain the accounting engine. If you have questions about it’s capabilities you might try the IRC channel, email group, or subreddit to hear from those who know it better than me.

Plain text accounting works great with git or most any version control system.

As for invoicing, we could make it less manual and take care of the HTML to PDF conversion in the Nextcloud app. Here is what we currently have planned for the first milestone but we’re open to discussion.

1 Like
15

I am the biggest proponent of text-based everything. But accounting is among the few domains where I think a text-only system would not work other than for geeks who are willing to dedicate much time for it.

The fact that a text-based system is needed to prevent lock-in is inaccurate. If you want to export your data to another package, most packages offer text export, or better yet – QIF export, which is more likely to be understandable by the new package you’re using. You need the data in text format just when you move it out, not during its entire lifetime, and I would argue that plain TXT is useful only for searching for strings; it’s not as any other package will be able to use this data as it is.

On the usability front, an accounting app is more than an interface to enter data verbatim like with a text editor. It supports quick entry, consistency guarantees, reminders, and other features to ease the day-to-day entry work. So I would recommend that your NC app offers the useful fill-in forms to enter transactions (including complex transactions likes transfers, and split-category ones).

16

Hi @hrel,

I didn’t mean for this topic to be a debate over whether text is a good way to store accounting data. As @simonmichael mentioned above, “Plain text accounting has its own strengths, and a good-sized community of happy users who find it useful” but I agree it also has its weaknesses.

I agree text isn’t needed to prevent lock-in. The lock-in argument they make on plaintextaccounting.org is regarding open source vs commercial accounting software like QuickBooks. I think it’s reasonable to argue that in practice text formats are more likely to actually get shared between different software but who knows? I guess it doesn’t matter much.

Finally, I agree that most people, especially non-technical people, won’t be editing transactions with a text editor. I think it’s cool that it’s possible, especially in Nextcloud, but it’s not required. The UI can provide a more controlled way to do it.

I haven’t found an open source accounting software that works better for me than hledger. I suspect it’s because accounting is more data-centric than application-centric. The most important thing to have is an accurate journal of well-categorized transactions. Everything else is built on that.

Accounting isn’t my job. It’s a chore. One that many people just don’t do. For me the biggest obstacle to actually doing personal accounting was just getting that far. Hledger is the first accounting tool I’ve found that’s made it really easy. I also like that my accounting data remains private.

1 Like
17

Anyone interested in better understanding the pros and cons of plain text accounting, you are welcome to join us in the chat channels/mail lists/reddit where we can and gladly will discuss in full detail ! See links here: Home - hledger

18

@ryanb, I fully agree and can certainly relate to everything you said… :slightly_smiling_face:

1 Like
19

It’s great that @ryanb is bringing forward this app which provides a workflow that works for many people. Yes, it doesn’t work for everyone. We’ve heard the arguments against it, and for some people they apply and for others they don’t. I’d greatly welcome it if we move that discussion elsewhere and focus on supporting @ryanb in the development here! If plain text accounting isn’t for you, you’ll surely find other tools elsewhere.

How can we help to test the app?

3 Likes
20

I’m in the process of converting it to a Vue app. Once it’s ready I’ll post here and on gitub. If you’re watching this topic you’ll get a notification.

In the mean time if you have any feedback or suggestions, please share!

1 Like