initial commit.

Partway through a rewrite. I have some old files I didn't want to entirely delete.

1 files changed, 115 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..5d674af
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,115 @@
+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
+---------
+
+When creating a new user, if something goes wrong (illegal/existing
+name, password missmatch), it isn't "reported", and the user will be
+sitting at "users/new" without any feedback about what went wrong.
+
+The End
+-------
+
+Happy Hacking!
+~ Luke Shumaker