MessageManager: README
======================

MessageManager is a mailing list program, much like GNU Mailman, but
with sub-lists, SMS messages, and easier configuration.  Also, social
networking.

MVC/ICM/PAC
-----------

So there's a bit of a controversy on what MVC actually is (namely, the
C).  `Controller' is an ambiguous word, it means something different
in each of the above acronyms.

A common (mis)interpretation of MVC is actually more correctly
described as ICM.  In this (mis)interpretation `controller' is the
logic glue between the model and the view, where the original/correct
interpretation of MVC has the controller being the user's feedback,
which is considered part of of the view in this (mis)intrepretation.
This (mis)interpretation is ICM (view=interface).  Because of this, in
several places (here, and in code), I refer to interfaces as views. So
sue me.

MessageManager sort of has a interface-controller-model.

But it also has a bit of a God Class going on.  This might be
considered the controller in a PAC architecture.  But that would
require me to rework this section, and I want to get back to coding.

The relationship between ICM and PAC is:
 ICM
 P AC

We've got our main, "God" class, `MessageManager'.  It basically does
three things:
  1. abstract away all database access
  2. handle authentication (which is just #1 with password hashing)
  3. serve as a factory for all the other resources we may need

There are 4 objects that are models:
  - User
  - Group
  - Message
  - Plugin
These have a little logic in them, but are mostly just wrappers around
the various database getX and setX methods in MessageManager.  The
coolest thing that they do is handle permissions on whether the
currently logged in user can read or write to them.

The interface is in the directory `src/views' (the directory name
comes from the incorrect interpretation of MVC).  The Template class
provides a pretty low-level wrapper for (X)HTML, that should make
converting fairly painless, and makes it easier to generate pretty,
valid markup.  It also handles a few common cases (mostly form stuff).
These do a lot of what could be considered belonging to a controller,
but that is because most of what they do is directly operate on the
models, and any controller behavior is just validating/parsing data
from the view, and is view-specific. There were too many `and's in
that last sentence.

The controllers are basically made up of MessageHandler and the
plugins (which plugins to MessageHandler).  They are in charge of
parsing incoming messages, storing them into our message store, and
sending them out to recipients.

RESTful
-------

MessageManager is RESTful in design.

Here is a table(?) of all URIs in this application, and what HTTP verbs
they can each be expected to handle.

- index         GET the homepage
  |- auth       GET the current auth state
  |             PUT user credentials
  |- messages   GET a list of all messages
  |  |          POST a new message
  |  `- <msgid> GET a representation of <msgid>
  |- plugins    GET the current plugin configuration
  |             PUT an updated plugin configuration
  `- users      GET a list of all users
     |          POST a new user
     |          PUT an updated user index
     |- new     GET the form for a new user
     `- <user>  GET <user>'s info
                PUT updated user info

Now, there is only one URI that is expected to handle both POST and
PUT (`users'), let's ignore it for a moment. No URI that is expected
to handle both POST and PUT.  I haven't done this intentionally, but
it works out well, because it means that I can treat them
interchangeably.  This is nice because current web technologies make
it a pain in the butt to send/handle PUT requests, so I can just do
POST requests, even if it's the wrong thing to use.  So it doesn't
follow HTTP's original design, it's still RESTful, it just uses
different semantics to decide which verb to use.

Ok, now, that tricky `users' URI.  I've handled that it must handle
PUT and POST by noting that it is accessable at two URIs, `users' and
`users/index', and assigning one to each.  `users' handles POSTing new
users, and `users/index' handles PUTing an updated user index.

BUGS/TODO
---------

* Installer
  1. 'baseurl' in the 'conf' table is not set
  2. During stage 2 (first user creation) the stylesheet is not applied
     (probably due to number 1)
  3. The created user is not activated.
* users/index
  4. It is impossible to de-activate a user (that field is only sent
     if the box is checked, so you uncheck it, but that's never sent).

The End
-------

Happy Hacking!
~ Luke Shumaker