gnucash/libgnucash/doc/design/top-level.texi

@node Top Level, Engine, Introduction, Top
@chapter Architectural Overview

@strong{This whole document is completely outdated. Don't read this. All
function names and every described structure has changed
completely. Only read this if you want to know how gnucash looked like
in 1999. This is completely outdated!}

GnuCash is written primarily in two languages: C and Scheme. The
engine/server is written in C primarily for speed, portability,
stability and historical purposes. Much of the day-to-day workhorse code
is written in Scheme, primarily for its power, expressiveness and ease
of development.  The user interface is Gtk/Gnome, some of it written in
C, some in scheme, and some with the GUI designer tool Glade
@uref{glade.pn.org}.

GnuCash is 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.

GnuCash currently consists of the following modules:


@section The Engine

The @dfn{Engine} (located under the @file{src/engine} directory in the
GnuCash codebase) provides an interface for creating, manipulating, and
destroying three basic financial entities: Accounts, Transactions (known
as Journal Entries in accounting practice), and Splits (known as Ledger
Entries). These three entities are the central data structures of the
GnuCash financial data model.

The Engine code contains no GUI code whatsoever.

@subsection Query

The @dfn{Query} module (@file{src/engine/Query.*}) provides an interface
into the engine for finding transactions based on a set of criteria,
such as description, date posted, account membership, etc. Simple
queries can be combined using standard boolean operators.

@subsection File I/O

The @dfn{File I/O} module (@file{src/engine/FileIO.*}) provides an
interface for reading and writing a set of Accounts, Transactions, and
Splits to a binary file. This module is deprecated.

@subsection XML I/O

The @dfn{XML I/O} module (@file{src/engine/*xml*.*} and
@file{src/engine/*sixtp*.*}) provides an interface for reading and
writing the engine information to an XML format.

@subsection Backend

The @dfn{Backend} module (@file{src/engine/Backend*.*}) provides
hooks to allow different modules to be used for storing and retrieving
Engine data. There are two backends currently under development, a
Postgresql backend (@file{src/engine/sql/*}) and an RPC backend
(@file{src/engine/rpc/*}).


@section The Register

The @dfn{Register} (@file{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.


@section Reports

The @dfn{Reports} module (@file{src/scm/report.scm},
@file{src/scm/reports}) is a scheme (guile) based system to create
balance sheets, profit & loss statements, etc. by using the engine
API to fetch and display data formatted in HTML.

For the most part, this module uses the Query API to fetch the engine
information instead of using the raw engine interface. This design uses
Queries to extract the data and assemble it into a view-independent
format. This data is then be converted to HTML reports and/or graphs
such as bar and pie charts.


@section Graphs

The @dfn{Graphs} module implements GUI graphs such as bar and pie
charts. These graphs can be interactive in that the user can, for
example, move pie wedges, and 'live' in that the user can click on graph
subsections to see a detail graph or report of that particular
subsection.

This module is implemented using the GUPPI library being developed by
Jon Trowbridge (@url{http://www.gnome.org/guppi}).


@section Price Quotes

The @dfn{Price Quotes} module (@file{src/quotes}) is a Perl system to
fetch stock price data off the Internet and insert it into the GnuCash
Engine. This module requires the functionality of the Finance::Quote
module available from CPAN. The Finance::Quote module can fetch
price quotes from many different sources including Alphavantage
and several international exchanges.

The Finance::Quote module also supports fetching currency exchange
rates. GnuCash will be extended to allow the fetching and use of
currency exchange rates.


@section User Preferences

The @dfn{User Preferences} module (@file{src/scm/options.scm},
@file{src/scm/prefs.scm}) 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
(@file{~/.gnucash/config.auto}). This file is automatically
loaded upon startup.


@section QIF Import

The @dfn{QIF Import} module (@file{src/scm/qif-import}) provides
functionality for importing QIF (Quicken Interchange Format) data
into GnuCash.


@section GnuCash

The GnuCash module (@file{src/gnome}, @file{src/register/gnome} and
@file{src/*.[ch]}) 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. There
is an obsolete Motif interface which is not maintained and which is
removed in current CVS. There is also old Qt code (removed in current
CVS) which won't compile, and most/all functions are missing.