From 09dfe32eb6b538225686fd6ed0220240010bc574 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Mon, 1 Aug 2011 01:22:36 -0400 Subject: initial commit. Partway through a rewrite. I have some old files I didn't want to entirely delete. --- README.txt | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 README.txt (limited to 'README.txt') 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 + | `- GET a representation of + |- 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 + `- GET '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 -- cgit v1.2.3