part-overview.tex

% !TeX encoding = UTF-8
% !TeX spellcheck = en_US
% !TeX root = ledgersmb-book.tex

\part{Overview}
\label{part-overview}
% An overview should contain:

% * why read?
%   * problems being solved
%   * goals to be achieved
%   *
% * how
%   * erp

\chapter{What is LedgerSMB}
\label{cha-what-is-ledgersmb}

\section{Introduction}
\label{sec-ledgersmb-introduction}
LedgerSMB is an open source, web based \gls{erp}. An \gls{ERP} is a system
which supports business processes of all disciplines throughout the
organization, automating as much of those processes as possible. To
illustrate this, consider the process of selling goods to a customer
in a trade company. Typically, a customer will request a quote, which
Sales will provide. When satisfied he or she will convert the quote
to an order. Sales will register the order, leading to order-pickers
to collect one or more shipments. Upon completion, Finance sends
out an invoice and records the customer's payment. LedgerSMB supports
this process by automating the conversion from quotation to order,
order to shipment and shipment to invoice, as well as providing
pack lists and other production related documents.

LedgerSMB includes a
powerful framework which supports building your own extensions and
integrations with other applications. Through this philosophy, it
aspires to be \emph{the} (open source) integrated administration system.

The software is being developed by the LedgerSMB project with its
homepage at \url{https://ledgersmb.org/}.
However, the actual project activity can be witnessed at the Github
project site hosted at \url{https://github.com/ledgersmb/LedgerSMB} and
on the mailing lists or chat channel 
listed at \url{https://ledgersmb.org/topics/support}

Its open source nature allows you to download LedgerSMB and use it with any
infrastructure you like. So there's no vendor lock-in: you can
always take your data and set up your system with another hardware vendor
or set up your own hardware.

\section{Supported functionality}
\label{sec-ledgersmb-modules}
As most \glspl{erp} LedgerSMB's functionalities are grouped into modules.
Many modules are integrated parts of the base application.  New features
can be implemented in separate modules at first to allow evaluation of the
feature set.  When a it has become sufficiently stable, the new module may
be integrated in the base application. As of that time, the existing features
will be frozen, meaning that the utmost will be done to prevent it from being
changed.

These separate modules - which are called \glspl{add-on}\index{add-on} - have to be
installed separately.  After installation they become seamless parts of
LedgerSMB with no visible difference from the base application. An
additional benefit of having \glspl{add-on} is that they can follow different
release schedules and separate maturity levels than the main application.


LedgerSMB \ledgerSMBversion features the following integrated modules:

\begin{itemize}
	\item General ledger
	\item Payment and Accounts payable
	\item Invoicing and Accounts receivable
	\item Fixed asset accounting
	\item Time registration and invoicing
	\item Point of Sale
	\item Quotation and Order management
	\item Manufacturing
	\item Inventory (warehousing) and shipping management
	\item VAT reporting
	\item Controlling
	\begin{itemize}
		\item Project accounting
		\item Department accounting
	\end{itemize}
	\item Application administration
\end{itemize}

There are no known \glspl{add-on} available at this time.

With this list of modules and \glspl{add-on} LedgerSMB has been successfully
implemented in a wide range of companies of varying types and sizes: shops,
manufacturing companies and service oriented businesses up to as big as @@TODO million transactions, growing by 50,000 transactions (spread across \acrshort{AR}, \acrshort{AP} and \acrshort{GL}) \emph{per month}.

\section{Feature comparison with alternatives}
\label{sec-ledgersmb-feature-comparison}
@@@ TODO

Packages to compare to:

\begin{itemize}
	\item GNUcash
	\item OSfinancials
	\item ERP5
	\item Odoo
	\item xTuple
\end{itemize}



\section{System requirements}
\label{sec-ledgersmb-system-requirements}

The \href{https://github.com/ledgersmb/LedgerSMB/blob/1.10/README.md#system-requirements}{README file}
which comes with every LedgerSMB software release should be
considered the canonical source for system requirements. In summary, the
following technical components are required:

\begin{itemize}
	\item A web server (known working are Nginx, Apache, lighttpd and Varnish)
	\item Modern Perl 5, with \href{https://github.com/ledgersmb/LedgerSMB/blob/1.10/cpanfile}{additional modules}
	\item PostgreSQL 13 or higher
    \ifpdf
	   \item (optional) \LaTeX{} or \XeLaTeX{} from the Te\TeX{} or \TeX{}Live \TeX{} distributions
    \else
    	\item (optional) LaTeX or XeLaTeX from the TeTeX or TeXLive TeX distributions
    \fi
    
\end{itemize}

More information about system requirements for clients and servers is available at
\href{https://ledgersmb.org/content/system-requirements}{https://ledgersmb.org/content/system-requirements}.

System requirements such as required RAM and number of CPUs and their speed
largely depend on the expected system activity. However, any modern \acrshort{VPS} should provide enough memory and storage to satisfy a reasonable number of users.

\section{Application architecture}
\label{sec-ledgersmb-architecture}

Due to its heritage from \href{https://sql-ledger.com/}{SQL Ledger} and the on-going process of rewriting
the inherited code, the architecture differs between parts
of the application: the old parts and the ones which have already been
rewritten.

Overall, the application consists of five layers:

\begin{itemize}
\item The web browser (as the user interface)
\item The web server (as a network traffic handler)
\item The Perl (web)server process (as an application - \gls{PSGI})
\item The database (as an application - \gls{PL/SQL}\index{PL/SQL})
\item The database (as storage)
\end{itemize}

In version 1.10 the user interface is a \gls{SPA}\index{SPA} using a mixture of new (e.g. 
\href{https://vuejs.org/}{Vue 3},
\href{https://webpack.js.org/}{webpack 5} and \href{https://developer.mozilla.org/en-US/docs/Web/Web_Components}{Web Components}) and old (e.g. \href{https://dojotoolkit.org/}{Dojo Toolkit}) technology.

The web server is an optional component that's highly recommended for TLS termination
and protecting the back end Perl HTTP server from malicious traffic\footnote{This setup is an industry-wide accepted best practice for deploying web applications; web servers like Apache or Nginx have been and continue to be extensively security-reviewed. No other implementations can achieve the same level of scrutiny.}. It may also be used
for serving static page components such as images, style sheets and JavaScript component as an efficiency measure.

Recent releases add separation between business logic and process state with the
latter being stored in the database and managed at the Perl layer.  Other than that, it's the Perl layer's responsibility to forward web requests to the database and
presenting the resulting data in response to the user interface.
The original goal to reduce the Perl layer to be a ``glue'' layer between the web
server and the database has been abandoned with  the introduction of this additional
(business process) layer.

At the ``database as an application'' layer, \gls{PL/SQL} functions implement business
functionality, such as creating \gls{COGS}\index{COGS} accounting entries.

The ``database as storage'' layer is responsible for storing data with consistency and
integrity; to that extent (and much more than in \acrshort{SL}) constraints and triggers
have been implemented.  An additional role for the storage layer is to enforce data
access rules; i.e. to protect data from being accessed by unauthorized users.

The main difference between old and new coding paradigms is at the Perl application
layer: older code generates HTML fragments while newer code delivers data through
web services.  As part of the on-going code restructuring, there's a major effort
to create a \gls{REST}\index{REST} web service based APIs.  The intent here is to facilitate
integration with other applications used by businesses (both in the business itself
or as provided by customers and vendors).






\section{License}
\label{sec-ledgersmb-license}

LedgerSMB is available under the terms of the
\textit{GNU Public License version 2}, in short: \textit{GPLv2}
\footnote{\url{https://opensource.org/license/gpl-2-0/}}.

The project attaches the following meaning to this license:
The copyright holders grant you the right to copy and
redistribute the software.  In case you make any modifications to the software
you're obligated to publish the changes \textit{if you distribute the software}.  You are always free to provide third party access to
the \acrshort{API} from your modified software without being required to disclose your changes.

The project considers the \acrshort{API} to include:
\begin{itemize}
\item Database tables
\item URLs with their input and output
\item Webservices of any kind
\item Function and object calls
\end{itemize}

The effect of this interpretation is that changes directly to the code base as well as inheritance of classes defined in the software constitute ``making modifications''.

\chapter{Reasons to use LedgerSMB}
\label{cha-advocacy}

Jack finds several tools which suit his requirements to some extent or another.
After evaluation of his options he decides to use LedgerSMB for the following reasons:

\begin{itemize}
\item Centralized data storage
\item Actively developed
\item Development team with security focus
\item Access to the application requires only a web browser
\item Integrated sales, shipping, invoicing, purchasing and accounting
\item Open source solution, so no vendor lock in
\item The roadmap appeals to him, because it has web services payrolling on it
\item There are multiple vendors offering commercial support, including hosted options
\item The developers envision building a platform out of it: creating the building blocks
required to build a company on
\end{itemize}


\begin{itemize}
\item Own your own data
\item Freedom to change
        \begin{itemize}
        \item Support organization
        \item Developer (organization)
        \item Data storage provider
        \item Application service provider
        \end{itemize}
\end{itemize}

\section{Internal control}
\label{sec-advocacy-internal-control}

Internal control\footnote{See also \url{https://en.wikipedia.org/wiki/Internal_control}}
helps organizations to prevent and detect fraud by introducing checks and balances
to assess effectiveness and validity of transactions in the organization and thereby
in its \gls{erp} and accounting system(s).

\section{Accounting principles}
\label{sec-system-accounting-principles}

The accounting guidelines \gls{ias} and \gls{ifrs} describe requirements
to financial statements (reports) and the underlying accounting process
\footnote{See also \url{https://en.wikipedia.org/wiki/International_Financial_Reporting_Standards}}.
Said requirements include qualitative characteristics:

\begin{enumerate}
\item Relevance
\item Faithful representation
\item Comparability
\item Verifiability
\item Timeliness
\item Understandability
\end{enumerate}

While some - if not most - of these characteristics relate to the process of accounting,
the ``Verifiability'' item clearly has an impact on the underlaying accounting systems:
In order to be verifiable, there must be a clear audit trail to show the origin of the
figures. To make sure users leave behind the required audit trail, some actions can't
be performed in LedgerSMB, even though it would seem to be a logical requirement to be
able to do so - from the perspective of a non-accountant.


\section{Impact of tight integration}
\label{sec-system-impact-of-tight-integration}

While both the qualitative characteristics from \gls{ifrs} and the checks and balances
from the internal controls are pose restrictions on the accounting process,
sometimes these restrictions require support from the underlying accounting
software.

One example is the support for creating reliable audit trails
by protecting accounting data from deletion. It's important to realize the scope
of accounting data in this respect: because invoices are being registered in the
accounts receivable administration - which is summarized in the general ledger -
they are part of the data for which the audit trail needs to be recorded.

Another example is separation of duties (also known as the ``four eye principle''),
where one accountant enters financial transactions and another is responsible for
posting them. This procedure protects the company from an accountant single-handedly
faking transactions and possibly masking fraud.

The requirements for good accounting processes and internal control have impact
on the work flows supported by LedgerSMB. As a consequence some of the work flows
described in part \ref{part-business-processes} may seem unwieldy; an example being the
lack of functionality to delete or correct incorrect invoices (See \secref{sec-business-processes-invoicing-correction-or-deletion} for more details).



\chapter{Introduction to accounting}
\label{cha-accounting-introduction}

The purpose of an accounting system is to keep track of the company's financial status.  The following reports are used to
present it:

\begin{description}
	\item[Balance Sheet] Provides a snapshot of the financial position of a company, listing its possessions (assets), debts (liabilities) and residual value (equity).
	\item[Income Statement] Also known as the ``Profit \& Loss Statement'', summarizes the income generated over a specific period and the expenses associated with it, resulting in ``Net Result''.
	\item[Cashflow Statement\footnote{\label{cha-accounting-footnote-not-implemented}Not currently implemented in LedgerSMB}] Summarizes the incoming and outgoing cash flows over a specific period, resulting in ``Free Cash Flow''.
	\item[Statement of Owner's Equity\footref{cha-accounting-footnote-not-implemented}] Summarizes the changes in equity over a specific period.
	\item[Trial Balance] An intermediate report used for preparing the Balance Sheet and Income Statement, tallies transactions over the reporting period; used to assert that all accounts in the General Journal are balanced.
\end{description}

The accounting system is composed of these parts:
\begin{description}
        \item [Journals] Contain the company's transactions with extensive additional data; they are the first point of entry for transactions, ordered by order of entry.
        \item [Ledgers] Contain aggregated data from the journals, ordered by date.
        \item [Chart of Accounts] The categories by which financial data are classified.
\end{description}

All accounting data ends up summarized in the \acrshort{GL}. Transactions may be entered in a different (sub)ledger before ending up in the \acrshort{GL}; e.g. the Sales Ledger. With the advent of computerized accounting, the use of journals is in decline: transactions are classified while directly being entered into ledgers.

In addition to the parts mentioned above the following terms are used throughout this document:
\begin{description}
        \item [Assets] Money and anything that can be converted into money without reducing
        the net equity of the business. Assets include money owed, money held, goods
        available for sale, property, etc.
        \item [Liabilities] Debts owned by the business such as bank loans and unpaid bills.
        \item [Equity] What would be left for the owner if all the assets were converted to
        money and all the liabilities paid off.
        \item [Revenue] Income from business activities.
        \item [Expense] Money paid to operate the business.
        \item [Cost of Goods] Money that was spent to acquire material and services to build a product being sold.
        \item [Operating Expenses] Expenses that are consumed to administer the business.
        \item [Accounts Receivable] An asset on the books as a claim for a future payment
        from a customer.
        \item [Accounts Payable] A liability on the books for a future payment to a supplier
        or vendor.
\end{description}

\section{Double-entry accounting}
\label{sec-accounting-double-entry}

The basic concept in double-entry accounting is that every transaction is an exchange. For example, when a business
sells goods to a customer, it issues an invoice.
The exchange is to provide the goods and receive the right for (future) payment. When the customer later pays the invoice, the right for payment is exchanged for cash.

Each exchange is to have the same value on both sides of the exchange, making sure no transaction is incomplete. This is where
the requirement comes from that double-entry transactions need
to be balanced.  It can occur that a customer's payment is a bit short of the owed amount.  Should the company decide not to pursue payment, the transaction would end up being unbalanced. After all the exchange is not equal-value between the providing and receiving sides. Double-entry accounting accommodates this scenario by explicitly recording the unpaid amount as an expense.

Because every transaction is balanced, so is the balance sheet. Through this approach, double-entry accounting provides strong
control over correctness of the numbers: as soon as a transaction
is unbalanced (i.e. contains an error), the balance sheet becomes unbalanced -- a relatively simple check.

\section{Cash versus accrual basis}
\label{sec-accounting-cash-vs-accrual}

Financial statements, such as the Income Statement and Balance Sheet can be prepared using either a cash or accrual basis.

In \gls{cash basis}\index{cash basis} accounting, the income is deemed earned when the business physically
receives the customer payment, and the expenses are deemed incurred when the business
physically pays them. Cash basis accounting does not require the use of purchase orders,
invoices, or long term liabilities.

In \gls{accrual basis}\index{accrual basis} accounting, income is considered earned when a valid asset is
received for services or product provided. The asset is the claim on the customer,
by way of the invoice, to collect an amount at a later date. This asset is called
Accounts Receivable. An expenses is considered earned when a liability is created,
by way of a purchase order, to the supplier or vendor. The liability is the commitment
to pay the supplier or vendor at a later date. This liability is called Accounts Payable.
Accrual basis accounting requires the use of invoices and purchase orders.

There can be a number of problems with \gls{cash basis} accounting:
\begin{itemize}
        \item No visibility in the accounting system regarding your cash commitments leading
        you to think you have more or less money to spend than you actually have.
        \item No visibility in the accounting system about unpaid customer debts.
        \item Your taxing jurisdiction may limit businesses that can use cash basis accounting.
        For example in the United States, if you sell products or services on credit,
        have gross receipts higher that allowed, or need inventory to account for income.
        \item  Because cash basis accounting isn't part of any accounting standards, there are varying expectations of what a cash balance or income statement looks like.
\end{itemize}

\section{Valuation of inventory}
\label{sec-accounting-valuation-inventory}

@@@ TODO Need why is this important paragraph?

The cost of inventory, in theory, includes all costs incurred to acquire the goods and make 
them ready for sale. This theoretical cost may include shipping costs, discounts, insurance, 
receiving costs, handling costs, storage costs, etc.

In practice, the cost used is often limited to the total invoice price for the goods.
This formula may or may not include shipping and handling.
Other costs are often ignored if they are immaterial to the overall cost of the inventory, if there
is no easy way to allocate the costs to the inventory, or they are relatively constant period to period.

Inventory valuation must consider in the following situations:
\begin{itemize}
        \item When the valuation of inventory varies from purchase to purchase. The costing method
        determines the valuation.  This situation is automatically handled in LedgerSMB using one of the
        inventory valuation methods discussed below.
        \item When the valuation of inventory is less that what was paid for it. The inventory must
        be written down. This is usually a manual calculation that is the result of damage, obsolescence, 
        or decline in the vendor or suppliers selling price.
        \item When estimates are required, such as when inventory is stolen, destroyed, or when a physical inventory
        cannot be performed. In this case, a reasonable and consistent manual method must be used to 
        estimate the value. 
\end{itemize}

There are several general automated inventory valuation methods including the following:
\begin{itemize}
        \item Specific Identification -- Each specific inventory item has its cost tracked individually. 
        This method is usually used for large and expensive items that can be tracked by 
        serial number or identification tag. 
        Typically, the specific identification inventory valuation method results an inventory valuation
        close to value of using the \gls{FIFO} method.
        \item \gls{FIFO} -- This method is similar to selling the oldest product first merchandising policy.
        In the \gls{FIFO} method the lastest costs are included in inventory cost and the older costs
        are charged back to \gls{COGS}.

        \gls{FIFO} is the preferred method for maintaining accurate historical costs and is less 
        susceptible to income manipulation by the timing of new purchases. Typically \gls{FIFO}
        results in the highest inventory value of these methods.
        
        % https://github.com/ledgersmb/LedgerSMB/blob/master/sql/modules/COGS.sql
        In LedgerSMB the inventory cost is tracked on a \gls{FIFO} basis. When a part is purchased, 
        its cost is added to the inventory asset account. When the part is sold, the cost of the item
        is moved to the cost of goods sold account.\\
        @@@TODO Is this paragraph redundant?\\
        @@@TODO  What sold cost is used; oldest, newest, average?\\
        @@@TODO How is the inventory asset account debited?
        \item \gls{LIFO} --  Under \gls{LIFO} the costs of the last goods purchased are charged
        against revenues as the \gls{COGS} and the inventory is composed of the costs
        of the oldest goods acquired.
        
        \gls{LIFO} is preferred when prices are rising as it typically results in reducing net income and
        thereby reducing taxes. However, \gls{LIFO} allows manipulation of income by simply changing the time
        at which additional purchases are made and does not represent accurate historical costs. 
        Typically \gls{LIFO} results in the lowest inventory value.
        
        \item Weighted Average -- Under the weighted average method, the total number of units 
        purchased plus those on-hand at the beginning of the period is divided by the total costs
        of purchases plus the cost of the beginning inventory.
        
        Typically the weighted average inventory valuation method results in 
        an inventory value between \gls{FIFO}, which is the highest,
        and \gls{LIFO} which is the lowest.
\end{itemize}