This document describes the requirements for a simple billing management web application. These requirements and this application serve two purposes:
- provide simple customer billing system for OQube company using non-standard and open-source software (ledger, latex)
- compare different web application development frameworks and technologies on this simple example
For goal n.2, it is expected that these requirements are simple enough to be implemented without requiring much efforts yet complete enough to exercise various parts of a WADF:
- gui development,
- application workflow
- model use,
- self-documentation,
- backend versatility,
- ...
Base requirements and functionality
General requirements
The application billing is to be used by SOHO that provides service for various customers, each customer being served for one or several different projects. Billable items for each project are recorded at random times and bills are issued either periodically (eg. monthly, quarterly) or at any other appropriate time, when the user sees fit.
The status of each project and each customer can be viewed with basic informations (name, contact info, locations...) updated easily. This status report should include:
- past bills issued with amount and summary
- currently billable items
The application shall start with a global status page with summary for each customer of billed/billable items.
Projects and customers shall not be deleted if bills (resp. bills and projects) exists in the db for these projects/customers.
When a bill is issued, this generates proper transactions into the ledger system and produces a latex then PDF file that is sent to the client. The latex source is saved on the server's filesystem.
Technical requirements
The application should be usable from any modern web browser (firefox 1.X and IE6+) and behind the most strict firewalls (ie. no applets, no activeX) and under the lightest platform requirements (ie. no javascript, no platform specific feature). The server part shall be accessed through an Apache 2 httpd server front-end on the same or different host. Authentication is not to be handled by the application, but is handled at the web server level. The chosen platform is linux (specifically ubuntu dapper drake).
Transactions read or issued are expected to use the ledger flat-file format and application. Alternatively, ledger can produce XML format which can be used by the application in read-only mode. Other long-term storage should be done in XML format using plain files or XML native DB server.
For the sake of simplicity, the application may assume access to some underlying structured storage and provide a SPI in application's language to be implemented for specific context of execution. This means that data access details are abstracted away as method calls providing specific objects or data-structures in native language of applications.
Apart from the above, there are no requirements on the language/framework/system used. The application must of course run on the expected platform. Of course, all necessary applications or libraries must be open-source products.
The application may be used by several simultaneous users and access to backend should be properly secured (ie. using transactions, locking...). The application should respond reasonably fast, although no precise requirements are expected at this stage.
Detailed specifications
Data
Domain model
The domain model is made of the following classes[1]:
- Account: an entity that may be billed (usually a customer). Attributes:
- id: unique integer
- name: a string
- address: a string
- currency: a string
- projects: a list of references to projects managed under this account
- contact: main contact for this account
- Project: a ... project !
- name: unique string (within customer)
- description: string. Short description of project purpose and goals
- contact: contact reference for this project
- account
- Contact: a physical person
- id: unique string
- name: string.
- phone: string. phone number of contact
- account: reference to account
- Item: billable item. May be either fees or expenses.
- id: string. transaction number
- description: string
- unit price: a price
- quantity: an integer
- currency: a string
- vat: a percentage
- project: reference to project for this item. may not be null
- bill: bill reference for this item. May be null.
- Bill: an issued bill
- id: a unique string, bill number
- date: date of
- items: reference to items in this bill
- validated: boolean flag
- account: account this bill pertains to
- Currency : current value of currency
- id: string
- base: reference to main currency
- value: amount of base this currency evals to
Parameters
Various parameters may be set to customize the behavior of the application.
- customize the (latex) format for outputting bill. This allows setting headers and footers that enclose the issued bill. These headers may contain references to the model's variables in the forme bill.account.contact.name for example. These variables will be filtered during bill generation
- customize ledger's layout
Behavior
Use cases are mostly standard CRUD operations on various parts of the model.
Account
- looking for an account: search by exact/approximate ids, names, contact names and project name. Returns a list of matching accounts.
- creating a new account: duplicate ids are checked.
- list of all accounts: present a list with ids, names and billable items total for each customer. each item give access to account's details, allow deletion of account or billing of pending items.
- display an account's details: allow modificatoin of account's attributes and adding of a project.
- bill : returns a bill with all pending items for this account, sorted by projects with sub-total and vat calculation.
- if it is validated, then the corresponding transactions are stored in the ledger base, a latex source and pdf file are generated and returned to the client
- if cancelled, return to account's details
- no bill is issued if there are no items
Project
Basic crud operations:
- create new project: A project may not be created without an account's reference. A new account can be created on the fly while creating a project. Same holds for contacts.
- list projects matching a certain criterion, then display details of project which contains all pending billable items for this project.
- display a project's details: allow modification of project's attributes and adding of items.
- deletion of a project: either from list or from details
Contact
- create a new contact: a contact may be associated with zero or more accounts and projects.
- list contacts matching criteria, then display details of contact with links to projects and accounts this contact manages. Allow deletion of contact from list or details form.
- update details of contact: allow modification of contact's attributes and linking to projects and accounts. Allow deletion of contact. Deletion of contact puts contact attribute of related accounts and projects to none (ie. null)
Item
- create a new item for an existing project. Alternatively, allow creation of project (and eventually account) from a new item. Uniqueness of id attribute is checked. VAT is a percentage on total price. Total value of item is calculated from quantity and unit price and displayed as a non updatable fields raw, VAT amount and total.
- list items matching criteria. List elements link to item's detail and item deletion. List distinguishes between billed and non-billed items.
- update an item. This is only possible if item is not billed (ie. is not linked to a validated bill)
Creation of an item entails creation of a ledger entry after validation. This entry is modified upon update validation.
Bill
- create a new bill for a given account. This generates a bill with all non billed items for this account, sorted by projects. Individual items may be selected or deselected. The total value of the bill, with and without VAT is displayed for all selected items. This value is calculated according to the account's currency after applying conversion ratio with items currencies. Note that this is automatically calculated by ledger.
- validate a bill. once validated, PDF output is generated and a new entry for this bill is added into ledger database.
- update a bill. Only possible for a non validated bill. May add/remove items.
- list bills matching criteria. Display list of bills' summary: account, date, totals, VAT, currency, validated flag.
- delete a bill. Possible only if bill is not validated.
Currency
Basic crud operation. Deletion is forbidden if currency is in use by some item or some account. Base of currency may be either another existing currency or itself.
Footnotes: [1] Although this model is expressed in terms of classes and methods,
this by no means implies that the application should be made using object-oriented languages, frameworks or models.