THIS IS OUTDATED AS OF DEME 0.4.0
For your own safety, always be careful to look at "last edited on" date at the bottom of the page...
- Overview
- Deme Architecture
- Storage: Database schema
- Storage: Directory Layout
- Folio items, Meeting area data
- Meeting Area Interface
- Other features
- Administration scripts
- Random development tips
- For PIECE developers
1. Overview
First of all, make sure to be familiar with Deme from a user's point of view. Learn from the live tutorial referenced on www.groupspace.org .
Deme runs on an apache/php/mysql platform on open-source unixes. So far it has only been tested on Linux (Redhat 9, php 4.2.2, mysql 3.23.58, apache 2.0.40)
Installation directions... currently, look at the README file.
A Deme installation on the server provides group spaces for any number of groups. A single Deme group is supposed to consist of a real-life group of people. Each group gets a set of its own resources:
-
Announcements
-
Library of files
-
more features to come: chat, etc.
-
but most importantly, a set of Meeting Areas, each of which can contain folio items and comments.
Each user can sign up for an account for the entire Deme installation. A user once signed in, then must join a group to participate in it.
A meeting area contains a number of folio items and a number of comments which may be associated with particular folio items.
2. Deme Architecture
Deme is programmed in PHP using a MySQL relational database as well as the filesystem to store data. It makes liberal use of Javascript, CSS, frames, and other client-side browser technologies to create a more dynamic interface than can be done in pure HTML.
Architecture diagram:
One somewhat unique aspect of Deme is that, especially for the meeting area, lots of UI logic exists not as PHP code, but rather as Javascript embedded through php files. The client's browser's javascript/dhtml engine actually does more UI work than the server's php engine, for the meeting area.
A design deficiency is that the main/ and marea/ php pages may interact either directly with the database (by executing SQL queries) or else indirectly through the object wrapper layer. Consistency through the object wrapper layer would be preferable, but it's often more convenient to directly execute queries from a php page. (For example, newpoll.php inserts a new poll row in the database directly, instead of creating a new Poll object than calling an store-in-database method.)
3. Storage: Database schema
important to know is there's a Meta database, which holds information about users and other things related to the entire Deme installation. There's also any number of Group databases, one per each group.
The schemas are in the .skel.sql files. The setup scripts use them to create new databases.
XXX describe the entire 0.2.0 schema?...
4. Storage: Directory Layout
Each group has its own subdirectory, in parallel layout to code/. The subdirectories in code/ are usually not used, but rather are templates to set up the subdirectories. An exception is for interface and operations that happen outside any one particular group, e.g. a user's home page.
[XXX andrew is this current and correct?]
-
deme-root-dir
-
code/ has all the PHP code and scripts for a single installation
-
lib/ - PHP code for include statements.
-
data/ - for each group, has group-specific data stored in individual files. Only for small things that would be too cumbersome to store in a database.
-
doc/ - documentation files (just a pointer to this wiki manual at this point)
-
main/ - PHP pages for non-meeting-area interface pages.
-
marea/ - PHP pages for the meeting area interface.
-
filestore/ - where actual files are stored, in a group dir. Not accessible by the browser. There's any number of subdirs looking like:
-
file_id [e.g. 1, 2, 5...]
-
blablabal.txt (or whatever)
-
files/ - to download a file, users access URL's that point to code symlinks stored in here. [this architecture should change, to a single file with no symlinks. instead alias via URL handlers, not filesystem symlinks] Under the current architecture, this is maintained to have the exact same structure as filestore/.
-
groups/
-
any number of sub-directories, one per group. Each group's subdir parallels the code/ dir.
5. Folio items, Meeting area data
Folio items are things that can be viewed and discussed in the meeting area. Folio items are viewed and navigated in the left pane; Comments on them are viewed and navigated in the right pane.
5.1. comments
There are a number of comments belonging to the meeting area. Each one may or may not be associated with an individual folio item.An individual message is represented as a row in the msgs table. It has its message text and references to its parent and the folio item it may refer to.
5.2. folio items
5.2.1. OOP -vs- SQL annoyances
Note that usually we think of data objects "containing" a list of objects. In a relational databse, representing this can take two forms:
-
have one column "list_of_bla" of a text/string type, with a format of being comma-separated, or a serialized php array, etc.
-
have a separate table for the subitems, with a who's-the-owner table. Thus every message in msgs knows which marea is its owner; the one specified by discoowner_id. (This is a bad quirky naming scheme; in all other subitem tables, the column name is just the same column name as in the owner type; thus table docs has a column marea_id denoting to which marea each individual doc belongs.)
5.2.2. the folio items
Current folio item types include
-
Discussion Items (discoitems, class Discussion Item)
-
Documents (docs, class Document)
-
Decisions
-
Polls
-
XXX more of them
XXX go through every single one and explain their oddities as well as marea/ related code.
XXX new-poll.php is crazy, see comments there
XXX make sure to explain the model for Decision system and php "polymorphism". The nascent command line testing framework for decision making code.
6. Meeting Area Interface
7. Other features
library, member list, bulk subscribe....
8. Administration scripts
addgroup.sh, rmgroup.sh
see README for their usages
