1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
|
Design Quickie Overview
-----------------------
by Linas Vepstas, January 2003
Overall Structure
-----------------
GTT is, today, a fairly small, simple application. It is big enough to
have a handful of semi-independent components, but small enough that it
is manageable by one developer.
GTT four basic parts:
1) the 'engine', a set of C objects that encapsulate
project, task and time interval data with a set of
GUI-independent programming API's. The API is in proj.h,
the code in proj.c and the private data structs in
proj_p.h. The goal of splitting out the data this way is
to make it easier to write an SQL back-end for storage,
and/or to interface to the web via cgi-bins.
2) some code to read/write the structs to an XML-formatted
file. The code in in xml-read.c, xml-write.c
3) The 'journal' code. This code displays the diary
of project activity as html, inside the gtkhtml html
widget. It uses scheme as an extension language, so
that the user can design custom forms. The code is in
ghtml.c. The design should be sufficiently abstract
that it could be piped to anything (e.g. to cgi-bins
in apache).
4) The Gnome GUI. This is most of the rest of the files,
including the parts of the GUI done up with glade.
Projects, Sub-projects, Tasks and Intervals
-------------------------------------------
An 'interval' is supposed to just be a record of a timer start & stop
and not much more. (see, however, 'interval fuzz' below).
A 'task' is supposed to be just a text memo associated with some
intervals. Think of a task as a kind of a "diary entry": a place
where you can write down what you did today. You can't go back
and restart old tasks because you can't go back and re-live yesterday.
(Tasks are mis-named, and should probably have been called 'diary
entries').
If you want to 'restart' a task, then what you should really do is to
set up a set of sub-projects. Projects & sub-projects can always be
restarted: that is what a sub-projects are supposed to be.
All About Billing
-----------------
There are four supported billing rates: regular, overtime,
double-overtime and flat-rate. The dollar values for these are stored
in the project structure. Which of these to use is an enum associated
with a task. 'flat_rate' is what it sounds like: the amount to bill
for the task, independent of the actual time spent.
Tasks can also be classed as billable or not in four ways:
billable -- go ahead an bill for this.
free of charge -- print on invoice but price is zero
not billable -- do not print on invoice.
hold -- potentially billable, but still being edited for correctness.
Tasks have a bill unit: everything on the bill will appear as a
multiple of this value. Typically 15 minutes or an hour. Interval
totals less than this are rounded up to a bill unit.
Interval Fuzz
-------------
If users need to hand-enter ex-post-facto hours into gtt, they may not
exactly remember the exact start time, down to the exact second.
Their memory is fuzzy. The interval 'fuzz' is used to indicate
how uncertain the start time is. Typically, its 0, 300, 900 or 3600
seconds. If set to 12*3600, it just means "I did this work sometime
today", but is otherwise vague about when. (So, for example, in this
case, the start time should be understood to indicate a day, but not
a time.)
Just because the fuzz is set doesn't mean that the interval is
inaccurate. Its still assumed that the interval is correct down to the
last second.
Notes vs. Memos:
----------------
Memo's are meant to be printed on invoices, whereas notes are meant to
be kept internal, not shown to the customer.
Custid
------
Customer id. Not used at the moment, future hook for customer
name/address/vcard,etc. info for invoicing.
Automatic Backup
----------------
Code in main.c performs automatic backup of the data files.
It saves once a minute for the first 4 minutes, then once every 4
minutes for the first 16 minutes, then once every 16 minutes for
the first 64 minutes, etc., forever. There is nothing to adjust,
there is nothing to configure, and the old copies are pruned
automatically. Because of the logarithmic distribution, it means that
even if you run for years, you won't have more than 20 or so backup
copies (viz. every 4 months for the first 16 months, etc).
The algorithm seems safe: the code never actually deletes files,
it only renames them: The pruning works by copying a newer file on top
of an older file. Thus, even if the app goes totally wacko, it can't
wack much: there's no chance of an 'rm *' happening by accident.
Future Plans
------------
GTT is as much an application as an experimental platform for application
development. I would like to explore the following with GTT:
-- Make the interface highly user-configurable. There are many application
development frameworks that try to provide this but none are defacto
market leaders, and none offer the right mix between domain ontology
(the stuff that should be 'hard cocded') and what should be user
configurable.
One thing I want to explore is how to build and integrate an 'application
designer' into gtt. The point being that a highly-configurable app
requires a rather complex preferences dialog. This should be split
off as a stand-alone application, so that naive users aren't bothered
by it, but power users can make use of it.
|