Chronica

     [Client]
        /\
        ||
     {network}  http/xml
        ||
        \/
[Server-Middleware]
        ^
        |  sql
        V
 [Database backend]

The client and server communicates via a http-like protocol, encapsulating XML data.

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).

GET JOURNAL PROTO1.1\n
encoding: utf8\n
patientid: 1505050505\n
user: johndoe\n
\n

This query will be made if the client requires the journal of 1505050505 on behalf of johndoe.

GET JOURNAL REPLY PROTO1.1\n
encoding: utf8\n
status: 0\n
size: 4242\n
\n
[4242 of body xml data]

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:

GET JOURNAL REPLY PROTO1.1\n
encoding: utf8\n
status: 1\n
size: 23\n
\n
Patient does not exist.

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.

PUT JOURNAL PROTO1.1\n
encoding: utf8\n
patientid: 1505050505\n
user: johndoe\n
size: 4242\n
\n
[4242 of body data]

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.

PUT JOURNAL PROTO1.1\n
encoding: utf8\n
patientid: 1505050505\n
user: johndoe\n
parent: 0a75fc9
size: 4242\n
\n
[4242 of body data]

This would mark the entry with id 0a75fc9 obsoleted/deleted and insert the body as a new entry updating the old one.

PUT JOURNAL REPLY PROTO1.1\n
status: 0\n
\n

This reply indicates that the insertion went well.

GET JOURNAL REPLY PROTO1.1\n
encoding: utf8\n
status: 1\n
size: 22\n
\n
Parent does not exist.

This reply indicates that something went wrong. Again the status field might be used later on to clarify the error.

{
 uid, cpr,
 parent, eve, del, deleted_by, deleted_time,
 timestamp,
 creating_user, owning_user,
 content
}

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).

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).

{
  userid,
  username,
  ...
}

This needs some revision…

Explained by example…

<?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>

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.

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).

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.

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.