Architectural Overview

GnuCash aims to be modular, thereby allowing separate individuals to maintain, develop and enhance certain modules without disturbing the overall development. (Never mind that modules help avoid spaghetti code and nasty, ugly hacks). The interfaces between modules are documented, and, for the most part, stable and unchanging. This block diagram shows major components.

GnuCash currently consists of the following modules:

Module Description   Engine The Engine (located under the src/engine/ directory in the GnuCash codebase) provides an interface for creating, manipulating, and destroying six basic financial entities: Accounts, Transactions (which record a sale/purchase on a given date), Splits (which record the balancing components of a transaction: the amount, the account involved), Lots (which identify that the physical item sold in one transaction is the same one that was bought in another), Prices and Currencies/Commodities. These six entities provide the central data structures of the GnuCash financial data model, as illustrated in this diagram. Additional structures are created by the business component. The Engine code contains no GUI code whatsoever, and is essentially OS-neutral. It is written entirely in C. It was designed to be used in a stand-alone server; however, it is not currently used as such.   Query The Query module (also in src/engine/) provides a generic mechanism for performing complex, structured queries on a collection of objects. For example, GnuCash uses queries to find transactions based on a set of user-sepecified criteria, such as description, date posted, account membership, etc. Simple queries can be combined using standard boolean operators. The query subsystem is a true generic object-query system, independent of the financial structure in GnuCash, and is slowly being spun-out as a stand-alone component at qof.sourceforge.net. Note that Query works closely with the data storage backend, so that the local collection of objects in the GnuCash engine acts as a 'cache' for a possibly much larger set of data in the SQL backend. The idea is to keep GnuCash 'scalable': the runtime size can stay small, while still having high-performance interactions, even when dealing with large, remote databases.   Storage Backend The Storage Backend module (src/backend/) defines a generic interface for storing GnuCash data (into files or databases) or for communicating with a remote GnuCash storage server (by any server-defined protocol). Currently implemented and supported are the XML file backend, which stores GnuCash data in its native XML file format, and the Postgres SQL backend, which supports multiple simultaneous users of GnuCash. Additionally, there are several experimental backends (currently broken/unsupported): one for communicating with a GnuCash storage server via RPC, and another that chats, via XML across HTTP, with a GnuCash server.   Register The Register (src/register/) implements a ledger-like GUI that allows the user to dynamically enter dates, prices, memos descriptions, etc. in an intuitive fashion that should be obvious to anyone who's used a checkbook register. The code is highly configurable, allowing the ledger columns and rows to be laid out in any way, with no restrictions on the function, type, and number of columns/rows. For example, one can define a ledger with three date fields, one price field, and four memo fields in a straightforward fashion. Cell handling objects support and automatically validate date entry, memo entry (w/auto-completion), prices, combo-boxes (pull-down menus), and multi-state check-boxes. Cells can be marked read-write, or output-only. Cells can be assigned unique colors. The currently active ledger row-block can be highlighted with a unique color. The register code is completely independent of the engine code, knows nothing about accounting or any of the other GnuCash subsystems. It can be used in independent projects that have nothing to do with accounting.   Reports & Graphs The Reports & Graphs module (src/report/) is a scheme (guile) based system to create balance sheets, profit & loss statements, barcharts, piecharts, etc. It uses the Query API to fetch and format data, which is then converted into HTML and displayed with the gtkhtml widget. Graphs are implemented in Guppi, (<http://www.gnome.org/guppi>). and are embedded (as live graphs) directly in the HTML.   Price Quotes The Price Quotes module (src/quotes) is a wrapper around the Finance::Quote Perl module, used to fetch stock price data off the Internet and insert it into the GnuCash Engine. The Finance::Quote module is available at SourceForge (or through CPAN). This module can fetch price quotes from many different sources including Yahoo, Yahoo Europe, and some international exchanges. Before a new data source can be added to GnuCash, it must be added to Finance::Quote first. The Finance::Quote module also supports fetching currency exchange rates. GnuCash will be extended to allow the fetching and use of currency exchange rates.   User Preferences The User Preferences module (src/app-utils/) provides an infrastructure for defining both user-configurable and internal preferences. Preferences are defined in scheme using several predefined preference types such as boolean, string, date, etc. Preferences are 'implemented' by providing a GUI which allows the user to see and change preference values. An API is provided to query preference values and to register callbacks which will be invoked when preferences change. Preference values which are different from the default values are stored as scheme forms in a user-specific preferences file (~/.gnucash/config.auto). This file is automatically loaded upon startup.   Data Import & Export The Import module (src/import-export/) provides functionality for importing QIF (Quicken Interchange Format) data files and OFX (Open Financial Exchange) files into GnuCash. One of the difficult aspects of importing data from a file is what to do if the file contains some data that has already been entered into GnuCash. This can happen when the imported file is a bank statement obtained periodically from a website: each time it is fetched, it might contain transactions that were previously reported. Thus, to perform file import correctly, one must have a fairly sophisticated transaction matcher that can detect and properly handle (ignore) duplicate transactions. This pattern matching is generically useful, and is used by the HCBI subsystem. (HCBI is an online banking system available to residents of Germany).   Small Business Features GnuCash provides support for a number of small business features, including a business-oriented ledger (which shows additional info that the regular, 'check-book style' ledger does not), Invoicing, Jobs & Order Entry, Tax Tables, and lists of Vendors, Employees and Customers. The structural organization of this code is similar to that of core GnuCash: there is a set of C objects (src/business/business-core)) that are saved/restored in the backend. The objects themsleves are manipulated by various GUI dialog elements (src/business/gnome)).   Recurring Transactions Scheduled transactions provide a mechanism for describing a set of regularly recurring financial transactions so that the GnuCash dataset can be automatically updated as time passes. The core object is the "Frequency Specification", which identifies a periodicity (daily, weekly, monthly, etc.). It is manipulated by a GUI widget. The FreqSpec is used with special "Template Transactions" that record info about how future transactions should be made out, and are manipulated by a corresponding GUI.   GnuCash The GnuCash module (src/gnome and other directories) is the main GUI application. It consists of a collection of miscellaneous GUI code to glue together all of the pieces above into a coherent, point-and-click whole. It is meant to be easy to use and intuitive to the novice user without sacrificing the power and flexibility that a professional might expect. When people say that GnuCash is trying to be a "Quicken or MS Money look/work/act-alike", this is the piece that they are referring to. It really is meant to be a personal-finance manager with enough power for the power user and the ease of use for the beginner. Currently, the Gnome interface is the only operational interface. An obsolete Motif interface can be fished out of historical CVS; but this interface has been deleted in the current CVS.