Django Ledger | Uniting Developers and Accountants for Innovation. with Miguel Sanda

So thank you, thank you for taking the time to come see this talk. And uh I got a question for you as a developer, you know, how many times have you dealt with the accounting team at one point in time after coding everything in your application? You know, everything is nice and clear. And then oops, you know, what does this mean from an accounting perspective, right? Now all of a sudden all that work is there and you're having to have a lot more conversations to make sure that your application now somehow funnels into the accounting books. So let's get started. So what is the problem that we're trying to solve here? Okay. So as developers, we're kind of used to

um developing application in in in what I call a single entry development, right? So basically typically you have an application database. And you have your transactions nicely done. You have your transaction ID, the timestamp, the amount. This is very common in applications like e-commerce, like you know, anything like subscription uh software as a service applications and things like that. Uh so but the real problem is how do you translate that into something that that is uh makes sense for accounting folks? and and finance, right? Like the accounting department and all these things, right? So they these guys they used to they think in assets, liabilities. in equity, right? And this is like you know two separate domains, you know, two sep

two different kinds of uh uh ways of thinking. Uh usually uh this translation What it means is just times and resources, right? Because if we knew exactly how these transactions funnel into the books from the moment they're originated, then we don't have to deal with this translation problem between the application application database and a financial statement. Right, so this is the main problem that Django Ledger is trying to solve. Being proactive in defining standard behavior So we can translate the application logic into financial logic from the moment it actually happens.

So that's a mouthful. So now let's just put it into perspective. Django Ledger is a Scalable, extensible, double entry, bookkeeping, and financial analysis framework that is built on top of the Django framework. Now what that means is that it leverages everything that we know about Django, the scalability, the security, the stensibility. And we take advantage of the Django models. So we don't have to reinvent the wheel when it comes to dealing with the database or dealing with security or dealing with user authentication. You know, we don't want to go there. We we just want to build on top of best practices and Django definitely help us get started faster. Now where it where it sets

uh the the the reason Django Ledger is so special is because it provides a high level API But the important thing here is that Django Ledger will provide a rapid collaboration between developers and accountants. So basically what that means is that Django Ledger is providing the playground. It's providing the environment. So these two uh very distant domains can interact in a way that we can set and we can code application behavior from the moment that is born. Not only that, it can be changed and adapted as the application evolves. So it is about being intentional when it comes to finances

the moment you define your application logic. Now with that, I'm gonna talk a little bit about me. Uh here you're gonna have a QR code where you're gonna find uh the presentation materials And you're gonna find the code that I'll be reviewing today. You can contact me, you can reach out to me, and everything. All the information is gonna be there. Uh but just a little bit about me. I am from Venezuela. Um and um I uh I live in Fort Mill, South Carolina, so it's just Two hours away from here. Not a bad commute, by the way, for those who have trouble twenty twenty hours. And I've been living in the United States for 18 years. So basically I have about 15 years of experience coding Python.

I'm a big RO fan, any RO developers out there. And also when it comes to the browser, I'll lean towards some some TypeScript. I have about 18 years of experience in the energy and financial sectors. And this is a little bit of a story about me. I have a civil engineering background. I don't come from the programming background per se. Uh after that, you know, I went ahead and did more engineering. Uh after that I went to business. I went to business school. And somehow I started having an interest in data science. And that's what I do today as a as as a full-time. But you know, at the end of the day, you know, this is

a story that I always tell everybody. I did all of this, so I end up in the place that I am today, which is doing what I love, which is programming. I made my hobby my career. And Django Ledger is definitely one of those things that are very close to my heart because I started this project about five years ago. And I started from the interest of doing my personal finances simpler. But at the same time, I knew where developers were coming from in the sense of uh you know these problems I'm I I may not be the only one facing these problems right so I wanted to do my own books I wanted to do my own things uh for for for for my um for my small business. Uh but you know this cannot be a thing that

uh this can be programmed in a way that can save a lot of time for developers. And that's how it got started. A pet project, and it grew into what it is today, Django Ledger. So let me tell you a little bit about Django Ledger and you know, the complexity that we are talking about here. So it is not just about transactions and Throughout this presentation, you will kind of get exposed to some concepts obviously that are related to finances and it may not be uh very uh related with the concept of programming, but this is the problem that we're trying to solve. Whenever we see something like this, credits and debits, you're talking accounting. You're talking bookkeeping. Right.

But here's here's the example of an online purchase purchase. Like we saw in the prior slide, you know, we we can have transactions. Like there's there's a sale of $120, which is the one above right there. But just that single transaction can trigger a ripple effect in the books that are not captured at the moment where uh when that sale actually happens, you know, in our application database. For instance, you can have merchant fees, you can have shipping costs, you can have accounts receivable, you can have cost of goods sold, inventory. These are debits, credits, you know, all the things that happen in the finance. side of things that ultimately will need to be sorted out for the company to even actually report on this.

And at the end of the day, the business owners they want to know where they stand financially. The applic they may find they may be able to fund the application, but you know they want to be able to know where they stand uh financially. So you could see here that debits, credits, there have balances, you know, sometimes A debit and a credit, you know, which is a uh a really uh touchy subject for for people who uh probably are confused about what a debit and a credit mean, but basically You can have situations where uh if you do a credit to an inventory account, for instance, the balance actually goes down. It doesn't necessarily mean it adds up. So and this is the problem that we're trying to solve.

So let's talk about a little bit about what double entry accounting systems are in today and what they mean in terms of you know from a database standpoint, right? So let's start with the entity model. The entity model is that company, is that legal entity, is that person, is that thing that you want to keep the books and that you want to do finances on, right? So that is the who. Who is are these books you know related to? Now then you have something called the journal entry model. Right? The journal entry is really the brains of the operation. So the journal entry is what captures things like timestamps. When are things happening? Right? It validates and applies accounting rules, debits to credits, credits to debits, a debit to a debit account, a credit to a credit account.

It keeps track of the balance. And basically answers the question when? When is this happening? Now the next step is the transaction model. And you could see how one entity model can have multiple journal entry models and one journal entry can have a multiple transactions model but basically now the transaction model is the is how much how much means that basically you allocate money to a specific account And you do a debit or a credit to a specific account. And then the chart of accounts model. The chart of accounts model is the bucket of money. It's your expense account, is your bank account, and so forth. Now, what the Django Ledger Core model does, it it it it introduces a new model, which is called the Ledger Model.

And when I started developing these applications like five years ago, Ledger didn't mean a lot of things that, you know, today ledger can mean um many different things. Uh but basically the ledger model in the context of Django Ledger, it means that it is a self-contained and extensible unit of accounting. And it's basically answering the what. What is this doing from an accounting perspective? To put it, you know, to give you an example, that could be a piece of property That could be a car, that could be a a cat cattle, it could be anything that your mind can relate to so you can describe your business operation in a way that you can start object oriented programming around it And what it does is basically self-contains the accounting to that particular

object. Now when it comes to the chart of accounts, Uh the chart of accounts is basically the list of accounts that are driving your your business, right? It definitely categorizes your business into your cash accounts, your bank accounts. Here's your inventory, then you have things like credit cards and things like that. But the way Django Ledger actually deals with this problem, and it is a problem because As you absorb legacy accounting and as you absorb new books and things like that, the description of the account may not be very specific, right? So it says checking account or it says checking or it says account or something like that. But from the standpoint of the program, we need to know exactly what is their role.

So the Django Ledger what does is it normalizes all the accounts into specific roles so we can attach this role to the specific account so Django Ledger knows exactly what it is It is inventory, it is cash, it is a a a a the credit card, it is income, and so forth Now, when it comes to journal entries, this is the brain of the operation. Basically, the journal entry model, what it's going to do is going to validate that the golden rule of accounting Credits must equal debits. And without that, really, there's no accounting system. The moment you have that freedom of entering any amount for any purpose,

That's where things start to go a little off and it they should not happen anyway. So Django Ledger incorporates checks every time a journal entry is done. or perform or or save to the database to make sure that all the accounting rules are are are validated before actually hitting the books So let's talk a little bit about ledger models. Okay. So like I said, the ledger model is how we implement object-oriented programming in the context of Django Ledger. So a ledger model again, it could be anything your heart desires. It could be if you're dealing with a real estate management company, it could be all the properties each

Each one of the properties that they own. If you're dealing with a rental car service, it could be the car, or if you're dealing with a farmer, it could be the tractor, it could be the field, it could be anything that relates to that particular business. Every entity is independent of the entire thing. So and every sorry, every ledger model is independent from the entity So a ledger model can produce financial statements on its own. So if you wanted to segregate the finances of a piece of property and you um Use the ledger to define that object that object is completely separate from the finances, but you can also generate the financial statement from the uh the entire entity So examples of that is again is

something like a rental property, a car, could be a super secret project, um, what if study anything could be an invoice, a bill So one of the key things about finances and and and financing systems, uh financial systems, is the fact of transaction controls. Okay? So what that means is basically what we want to make sure is that we incorporate common sense controls, uh leveraging some of the Django uh built-in like user model permissions. and uh authentication system to make sure that depending on the user, that user could have certain permissions to do certain things. And that is basic

uh, you know, when you see ERP systems, when you see financial systems, you want to make sure that not everybody can do all the things at the same time or certain things, right? So one of the things that Jang the the way Django Ledger solves that problem is that you have two separate controls, right? You have controls at the journal entry model, which is a list of transactions, is a model that keeps track of a list of transactions and the ledger model which is the object that is being modeled as a as as part of the uh uh the object oriented programming strategy right so A ledger can be posted or not, a journal ledger can not can be posted or not. So the question is, does that affect the books? So if you had a super super super

secret project that you're working on and it's completely hidden from uh the public view of the publication, uh you want to make sure that that is not posted yet. Or that never posts, by the way. So you could you make use of these mechanisms to uh to say hey this ledger will never post And it will never hit the books. The other option is let's post the journal entry so we can see it in the financial statements, but don't post the ledger The ledger keeps, you know, it's still away from from the books. So that does not affect the books. The option, the other option is you post a ledger, an empty ledger. uh without any journal entry being posted that does not affect the boots either. But at the end, what you want to do is that anything that hits the books

You want them to be posted. And there's controls that will built into Django Ledger that will let you uh control this this this flow of basically posting information into the ledger. Now the other the other thing that is important for users and for developers is the fact that You you cannot you can have multi-tenancy. Now let's just say that you are developing an application that is keeping track of multiple entities, in this case, multiple companies, multiple things. Uh you want to make sure that not all Django users have access to all the entities. And this is particularly useful if you are For instance, granting access to

a particular user that owns a particular entity. You don't want that user to kind of have access to the transactions of companies that are not related to that user, right? So this is enforced as the database layer. Every time we create an entity model It is enforced at the database layer. So throughout the code, and I will show you some code snippets in a little bit, you will see that it is you have to be very explicit about the user model you are using. uh for a particular operation. Just to make sure you f filter out any entity that that user does not have access to So Django users, the Django user model is one of the cornerstones of Django Ledger because it helps you assign

admins, it helps you assign managers. and isolate certain entities from the actual user database. Now let's do an anatomy of the request, right? What happens when you send a request to Django Ledger? And Django Ledger has several built-in views uh for for many different things, but this is the overall process of what is happening. So the user sends a request. Next thing it does, it lands on a Django view. The Django view will have two key uh keyword arcs that will are are um absolutely necessary to perform any operation. Number one, the entity slug, which is basically an identifier for

a company. It is created automatically when you create a new company. or the ledger primary key. Again, it's the company or the ledger. A company is really a group of ledgers. a logical grouping of ledgers which rolled up into the company. You know which company you want to want to look at or you know which ledger you want to look at. That's step number one. Step number two is having your user model fully authenticated That gives you access to certain uh uh entities and and certain things you can do. And from date and to date are two things that are important because if you're trying to pull a financial statement and I'll show you examples of that in a minute, you need to know, you need to bound it. If you're pulling a balance sheet, you need exactly through what date, December 31st, 2023, that

that balance sheet is going to be related to. Or if you're looking at an inco statement, you want to say from December uh December uh 1 through 31st. Now you have several other things like database query and this is the digest phase Basically, Django Ledger is fully optimized to take advantage of the database. It does a database query, it does a post-Python processing, and then introduces the concept of the financial middleware. And returns an I. O. context. Middle world samples are, uh can you can you check the the time for me? Five minutes? Okay. Middleware examples are things like groupings, like journal entries, like financial radio calculations.

Those are middleware examples. So let's start with a uh with a practical guide. Basically this code right here what what does is it introduces uh it shows you how to create an entity. Basically it's that simple. You import the entity model And uh you just call the create entity model and you pass in the user model, the entity name, uh, if you want to use the accrual count in the method and so forth. Uh you can create chart of accounts. Obviously a chart of accounts is the uh the house where you put all your accounts in If you are trying to populate an entity and you don't want to start from scratch, you can use the uh pretty handful

populate random data uh method. It will pretty much fill it in with all the information needed so you can start coding right away. Uh you can create accounts and this is this is another example of of of how you can create accounts and how Django Ledger lets you uh make better decisions, it kind of validates the code for before before it actually uh put it you put it in the database There are certain best accounting best practices that are followed, so you want to make sure that when you create the account, it's the account makes sense for accountants as well. Now the way Django Ledger works is by creating blueprint drive libraries. So basically if you're familiar with Django Ledger, uh sorry, Django template text. It is a similar API.

You create a library. That library is registered. And then what you what you do is you create Bruplints. And these blueprints is the playground where accountants and developers can actually collaborate on because it defines and parameters the behavior of your application. Now in three steps, real quick, because I'm short in time. Um step number one, you get a cursor. A cursor is based on the entity model and the user model. Step number two, you dispatch. Basically you dispatch the transactions that the the blueprint that you just created using the ledger model and the entity that you um that you're operating on. And step number three, you commit transactions.

So all of this is lazy. The dispatch, uh the dispatch dispatch call at the end of the day, will just compile all the instructions and do a single entry uh on the database. Now when that happens, basically it a journal entry is created and the journal entry number is generated. And this is an example of how the financial middleware is helping you uh kind of drive the financial operation. It's this this is information that the accounting department would definitely require you to have. uh a journal entry number, a date, the activity, and so forth. Now the way you produce financial statements is again calling the appropriate function

And that will return, you can see the for the balance sheet, the for the PL, for the cash flow statement, and that will return something like this. You don't have to read it, but basically, this is the information you need to know in order to continue your application development. This is all the accounts balance, you know, anything that you need to know about uh the finances of the application. Another key feature is financial statements in PDF format. It's really nice to share this with accountants and bookkeeping people. So that if they're not familiar with the application, uh you can definitely print those and share those right away. And one of the things that you can do with Django Ledger, it comes out of the box with an admin UI, which you can start Kind of like looking at the all the financial information.

You can create bills, you can create invoices. This is more of an uh a management UI kind of like uh tool uh which incorporates some billing invoicement, purchase overs and and so forth. And to finalize, this is an example application. Let's just say that we have an example an application where you're just going to do some payroll. So on the left, what you have is you the step number one, what you're gonna do is you're gonna define a payroll library and then you define a blueprint. To process some employee payroll. In this particular case, you're taking the growth pay and the tax bracket of that employee. And on the right, you have an employee model, which is inheriting from the ledger model. And you're pretty much extending the dead and model to incorporate the details needed for that employee.

First name, last name, date of birth, what's your salary, what's your tax bracket. uh and uh and then you can incorporate the functions necessary to just say uh process a payroll and what the process prayer what processing the payroll does is basically takes the pay date, the user model in this case, and just runs. the uh the blueprint for you. All the instructions are predefined in the blueprint, they're parametrized and maintained by the accounting team, but at the same time the developers have the flexibility to uh dispatch these functions without minimal intervention on the bookkeeping accounting side. Thank you so much. Once again, that is the QR code. You'll find the presentation, the notebook with all the materials

and the code, and I'll be available for questions after the presentation. Thank you.