======Chronica======
=====Overview=====
<code>
     [Client]
        /\
        ||
     {network}  http/xml
        ||
        \/
[Server-Middleware]
        ^
        |  sql
        V
 [Database backend]
</code>
The client and server communicates via a http-like protocol, encapsulating XML data.

=====Connecitons=====
The client establishes one TCP connection per session (patient id), and keeps this connection alive for the entire session.
The server middle-ware can use a single connection to the database, or optionally one connection per client session (if authentication or similar on this level is required).
The server is a forking server (forks on each incoming connection).

=====Protocols=====
====Read Journal====
===Query===
<code>
GET JOURNAL PROTO1.1\n
encoding: utf8\n
patientid: 1505050505\n
user: johndoe\n
\n
</code>
This query will be made if the client requires the journal of 1505050505 on behalf of johndoe.

===Response===
<code>
GET JOURNAL REPLY PROTO1.1\n
encoding: utf8\n
status: 0\n
size: 4242\n
\n
[4242 of body xml data]
</code>
This will be the answer if there exists a journal entry for 1505050505 and johndoe has the rights to read it.
If however something does wrong, the reply will look like this:
<code>
GET JOURNAL REPLY PROTO1.1\n
encoding: utf8\n
status: 1\n
size: 23\n
\n
Patient does not exist.
</code>
The value of 'status' indicating whether an error has occurred or not. Non-zero values other than 1 might be used at a later point in time to indicate more accurately what the error was (think errno in ''c'').
The contents of the body is an error message that can be introduced to the user.

====Write Journal====
===Query===
<code>
PUT JOURNAL PROTO1.1\n
encoding: utf8\n
patientid: 1505050505\n
user: johndoe\n
size: 4242\n
\n
[4242 of body data]
</code>
This would create a new entry in the journal of 1505050505, with the current timestamp as its creation time, and johndoe as the creater and owner.

<code>
PUT JOURNAL PROTO1.1\n
encoding: utf8\n
patientid: 1505050505\n
user: johndoe\n
parent: 0a75fc9
size: 4242\n
\n
[4242 of body data]
</code>
This would mark the entry with id 0a75fc9 obsoleted/deleted and insert the body as a new entry updating the old one.

===Response===
<code>
PUT JOURNAL REPLY PROTO1.1\n
status: 0\n
\n
</code>
This reply indicates that the insertion went well.

<code>
GET JOURNAL REPLY PROTO1.1\n
encoding: utf8\n
status: 1\n
size: 22\n
\n
Parent does not exist.
</code>
This reply indicates that something went wrong. Again the status field might be used later on to clarify the error.

=====Database table layout=====
====Journal Entry table====
<code>
{
 uid, cpr,
 parent, eve, del, deleted_by, deleted_time,
 timestamp,
 creating_user, owning_user,
 content
}
</code>
The ''uid'' is a unique identifier for this specific entry.
The ''parent'' is the identifier of the parent if this post obsoletes another one.
It will be its own identifier if there is no parent.
''eve'' is the root of an edit tree. Again it can be the entry's own identifier if it is itself the root.
''del''/''obsolete'' (or a non-empty ''delete_by'') indicates that this entry is exceeded by a newer entry.
''deleted_by'' is the username of the user actually deleting the entry. It is the empty string if the entry is not deleted.
''deleted_time'' is the timestamp of the deletion or 0 if the entry is not deleted.
''timestamp'' is the timestamp of the creation of the entry (insertion).
''creating_user'' and ''owning_user'' are the user ids of the creating and owning user.
''content'' are the utf8 encoded content of the entry (the body).

===Notes===
If it is to be defined that an entry cannot simply be deleted, without an exceeding entry the following fields might be removed from the row:
  * The ''del'' can be removed and replaced by looking for entries with ''parent'' as //this// entry's identifier.
  * The ''deleted_by'' and ''deleted_time'' fields can be replaced by looking at the exceeding entry's creator/timestamp (the entry with its parent pointing at //this// entry's identifier).

====User table====
<code>
{
  userid,
  username,
  ...
}
</code>
This needs some revision...

=====The journal XML format=====
Explained by example...
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<journal patientid="1505050505">
  <entry creater="johndoe" owner="johndoe" timestamp="1234567890" uid="6f3ce7" ... >
     utf8 encoded entry contents ...
  </entry>
  <entry ... >
     utf8 encoded entry contents ...
  </entry>
     .
     .
     .
</journal>
</code>
The XML format is to undergo heavy revision, but the basic structure of a flat document containing each entry in a separate tag will probably be preserved.

=====Notes on the Future=====
====PCPraxis compatability=====
The server must at each journal edit export a ''JOURNAL.TXT'' file compatible with pcp. This might be done through an insert-hook in the database. The file should also be written to ''JOURNAL.TXT.orig'', and a filesystem watch (using the ''inotify'' interface) be added, to discover if the journal file is written by pcp. In this case a diff must be made between ''JOURNAL.TXT'' and ''JOURNAL.TXT.orig'', and the result be inserted into the database. This will in term result in the writing of a new ''JOURNAL.TXT'' (invocation of the hook).

====Journal History====
A tree structured XML result might be introduced at some point, sending the entire entry history to the client, which might be shown in the GUI in some appropriate manner.

====Centralized User ACLs====
Everything should at some point connect with an LDAP server, making sure that the user has the correct permissions to access the journal in the way requested.