Copyright 2020-2023 Demian Harvill
MLedger is a microservice for describing and maintaining an accounting general ledger. It is written in Go, and uses gRPC to define and implement its application programming interface (API). The server requires a JSON Web Token (JWT) generated by the MService microservice for authorization.
Example client usage using the Go command line client (note that any thin client in any language supported by gRPC can be used instead):
**glclient create_organization --name my_company --sdate 2020-01-01 **
Create a new organization.
glclient get_organizations_by_mservice
Get all organizations defined for the MService account. Useful to determine the hexadecimal guid for other commands.
**glclient create_account_type --id 500 --type asset **
Create a new account type. The id is a numeric key that you assign.
glclient get_account_types_by_mservice
Get all account types defined for the MService account.
glclient create_transaction_type --id 7 --type invoice
Create a new transaction type. The id is a numeric key that you assign.
glclient get_transaction_types_by_mservice
Get all transaction types defined for the MService account.
glclient create_party --id 77 --name external_company
Create a party to be used by external transactions. The id is a numeric key that you assign.
glclient get_parties_by_mservice
Get a list of a all parties defined for the MService account.
glclient create_account --orgid 0123456789abcdef0123456789abcdef --name test_acct --desc 'test account' --type_id 7
Create a new general ledger account.
glclient get_accounts_by_organization --orgid 0123456789abcdef0123456789abcdef
Get a list of all general ledger accounts defined for the organization,
glclient create_transaction --orgid 0123456789abcdef0123456789abcdef --tdate 2020-01-02 --desc 'test transaction' --type_id 7
Create an internal accounting transaction (with details defined later). Returns a the numeric transaction id in the result.
glclient create_transaction --orgid 0123456789abcdef0123456789abcdef --tdate 2020-01-02 --desc 'external invoice' --type_id 7 --from_party 100 --via_key EXT12345
Create an external accounting transaction (with details defined later). Returns a the numeric transaction id in the result.
glclient add_transaction_details --id 12345 --json '[{"aid": "0123456789abcdef0123456789abcdef", "amt": "10.00", "debit": true}, ["aid": "3210456789abcdef0123456789abcdef", "amt":"10.00"}]'
Add details to a newly defined transaction, In the example, the transaction has key 12345. A debit of $10.00 is applied to account 0123456789abcdef0123456789abcdef and a corresponding credit to account 3210456789abcdef0123456789abcdef.
glclient get_transaction_wrappers_by_date --orgid 0123456789abcdef0123456789abcdef --sdate 2020-01-01 --edate 2020-12-31
Get all transactions (with transaction details) associated with the given organization between start and end dates.
Other commands for operations (eg. get, update, delete) can be discovered with
glclient
with no parameters.
The generated JWT uses RSA asymmetric encryption for the public and private keys. These should have been generated when installing the MService microservice; in particular, the mledger server needs access to the jwt_public.pem public key.
In a production environment, the connection between the client and the MService server should be encrypted. This is accomplished with the configuration setting:
tls: true
If using either a public certificate for the server (ie, from LetsEncrypt) or a self-signed certificate, the server need to know the public certificate as well as the private key.
The server configuration is:
cert_file: <location of public or self-signed CA certificate
key_file: <location of private key>
The client configuration needs to know the location of the CA cert_file if using self-signed certificates.
There are MySql scripts in the sql/ directory that create the mledger database (mledger.sql) as well as all the required tables (tb_*.sql). These need to be run on the MySql server to create the database and associated tables.
The persistent data is managed by a MySQL / MariaDB database associated with this microservice.
No data is shared across MService accounts.
The data model is inspired by "The Data Model Resource Book, Vol 1" by Len Silverston.
The root object is an organization, which is associated with a single MService account. It represents an organizational entity (company, department) which keeps its own accounting general ledger.
Each organization has a list of account objects, which is the chart of accounts. Each account has an account_type (such as asset, liability, expense, etc.)
A journal of accounting transactions is represented by a list of transaction objects. Each transaction is tied back to the organization, has a date, description and transaction_type. Examples of transaction_type are invoice, credit memo, depreciation, etc. For transactions that refer to an external entity outside of the organization, the from_party and to_party can be specified as well as the external key (posted_via_key) and external date (posted_via_date).
The list of party objects gives a directory of the external entities associated with external transactions.
Each transaction has a list of transaction_detail objects which give the explicit credit and debit details associated with the accounts referenced by the transaction.
To build the server:
cd cmd/glserver
go build
The glserver executable can then be run. It expects a YAML configuration file in the same directory named conf.yaml . The location of the configuration file can be changed with an environment variable,GL_CONF . Configuration can slao be specified using command line flags when starting the server, or through environment variables (with GL_ prefix).
glserver -h
Usage:
invserver [flags]
Flags:
--cert_file string Path to certificate file.
--conf string Path to inventory config file. (default "conf.yaml")
--db_pwd string Database user password.
--db_transport string Database transport string.
--db_user string Database user name.
-h, --help help for invserver
--jwt_pub_file string Path to JWT public certificate.
--key_file string Path to certificate key file.
--log_file string Path to log file.
--port int Port for RPC connections (default 50056)
--tls Use tls for connection.
A commented sample configuration file is at cmd/glserver/conf.sample . The locations of the various certificates and keys need to be provided, as well as the database user and password and the MySql connection string.
A command line client written in Go is available:
cd cmd/glclient
go install
It also expects a YAML configuration file in the user's home directory, ~/.mledger.config. A commented sample for this file is at cmd/glclient/conf.sample
Running the executable file with no parameters will write usage information to stdout. In particular, all subcommands expect the user to have logged in with Mservice acctclient to establish the JWT. The JWT is also used to determine which account is being used for the command.
Note that the use of the Go glclient is merely a convenience, and not a requirement. Since we are using gRPC, the thin client can be written in any supported language. It can be part of a web or mobile application for example.
The mledger microservice relies on the ledger claim, and the following claim values:
gladmin: administrative access
glrw: read-write access to mledger objects
glro: read-only access to mledger objects
Note that within an account in Mservice, a role must be created to map these claims to a logged-in user.