Add an architecture design draft

1 files changed, 99 insertions, 0 deletions

diff --git a/ARCH b/ARCH
new file mode 100644
index 0000000..d208fef
--- /dev/null
+++ b/ARCH
@@ -0,0 +1,99 @@
+distix architecture
+===================
+
+distix will store data as files in git. Each git repository holds data
+for one ticketing system instance only. There is some metadata about
+the repository (ticketing system instance), and then a number of
+tickets. Each ticket consists of ticket metadata and a Maildir with
+all the discussion about the ticket.
+
+I believe, very firmly, that e-mail is a good way to discuss problems
+such as those that are relevant to a ticketing systems. There are
+other good ways, of course, but e-mail is the common base that
+everyone has, and that works quite well. distix thus stores
+discussions as e-mails, and it stores the actual e-mails rather than
+trying to extract what I think right now is relevant from each e-mail.
+
+Maildir is a good way to store mails. Each mail gets a unique id, and
+this should make them easily mergeable with git.
+
+The metadata will be, at least in the beginning, in the form of
+key/value pairs. The key will be a string, and the value will also be
+a string. Keys may occur multiple times: in effect, the value is then
+a non-empty list of strings. This multiplicity is important so that
+users may, for example, do things like having a key for which
+supported branches a bug is affected by:
+
+    found-in-branch=supported/1.1
+    found-in-branch=supported/1.2
+
+I'll store the key/value pairs in YAML files. JSON would also be a
+nice choice, except it sucks for human editability, and doesn't,
+especially, deal well, from a usability point of view, with string
+values that contain many lines of text. While I don't expect,
+long-term, for distix users to edit the metadata files directly, I
+will have to, and so I care about the file format.
+
+I don't want to invent a new format myself. That's silly, and I've
+done it a few dozen times already, so I'm bored by it.
+
+Thus a metadata file will look like this:
+
+    key:
+    - value
+    - value 2
+    key2:
+    - value
+    - value 3
+
+Etc. I'll worry about namespacing keys later. I don't need to have the
+perfect format from start, and I'm not yet sure namespacing will be
+worth it. Right now, I care about having something simple that works.
+I'll worry about perfect later.
+
+The repository will have a layout like this:
+
+    repo.yaml               -- repository metadata
+    tickets/
+        TICKETID/
+            ticket.yaml
+            Maildir/
+
+I may later decide to have the TICKETID level be multiple levels,
+based on the ticket id, to avoid having too many tickets in one
+directory. But later, this is fine for now.
+
+If I decide to implement an "archive" feature, where tickets that are
+moved after they are well and truly done, and nobody cares about them
+anymore, and nobody calls, and nobody visits them, but they shouldn't
+be deleted either, then I'll add a top level "archive" directory. But
+we'll see, that's an idea for the future.
+
+I may add more metadata files, too, such as one for stored searches,
+or such, but, again, we'll see.
+
+I'll let git worry about merging. This opens up the possibility of
+merge conflicts. For now, I'll punt on that, and let the user deal
+with the conflicts manually. Later I may consider either a merge tool
+that git can call to resolve conflicts automatically, or change the
+metadata storage so that conflicts are very unlikely. But again,
+later, right now the important thing is to get something working so I
+can get experience with the concepts and feedback on what is actually
+working OK and what needs fixing.
+
+I'll make it so distix will make changes and also commit them to git.
+This avoids having the user have to do that manually. I'll also make
+it so that if there are uncommitted changes, distix will error out.
+
+
+Output from distix, to the user, will be produced via temlates.
+Initially, the templates will be with the distix code, but later I
+will add ways for the distix instance admins to use templates from
+elsewhere, for extra flexibility and theming.
+
+The use of templates is important. Avoiding to hardcode what is output
+and how it's laid out is a good thing from flexibility, and doing it
+from the beginning avoids accidentally hardcoding things. Since the
+web interface is likely to be implemented using bottle.py, I'll use
+bottle's templating system.
+