blob: 96d1c0238e46f5004b66d252996a96eae35b38e5 [file] [log] [blame]
#summary Melange Modules
#labels 2013DeveloperDoc
=Static Modules (How Melange Is Organized In Source Control Directories)=
==The "app" Top-Level Directory==
The "app" top-level directory contains all source control-based resources that will go into the code package that will be uploaded to App Engine as part of Melange's release. It contains several third-party code directories, the "soc" directory that contains Melange's first-party production code, and the configuration files and outermost scripts that mediate App Engine's interaction with Melange's code.
==app/soc==
app/soc is the root of Melange's first-party (authored by Melange developers) code. It is divided into:
* *cache*
** Melange's code that interacts with the App Engine memcache.
** Primarily used for XSRF tokens and determining which projects, organizations, and tasks are randomly featured on the home page.
* *content*
** Melange's static content (mostly images).
* *logic* (described below)
* *mapreduce*
** Melange's code for making changes to all instances of a given type of data.
* *middleware*
** Melange's code for interacting with Django's Middleware and Blobstore systems.
* *models* (described below)
* *modules* (described below)
* *tasks*
** Melange's code for interacting with App Engine's tasks system.
** Email sending is handled by this code.
* *templates*
** Melange's HTML templates.
** As of March 2013 the elimination of a "v2" layer of indirection is in progress in this directory.
* *views* (described below)
==Other Top-Level Directories==
* *mockup*
** Design assets from past site redesigns (mostly images and HTML).
* *scripts*
** First-party Melange code not included in the web application image of Melange.
* *tests*
** Tests and test utilities in a directory structure mirroring that of the top-level "app" directory.
* *thirdparty*
** Third-party code such as the App Engine SDK.
=="logic", "models", and "views"==
Melange code is in many places divided into three parallel packages named "logic", "models", and "views". At such places, (1) the "models" package will contain modules and classes making use of (and inheriting from) App Engine's db.Model class to describe how Melange data is persisted in App Engine's data store, (2) the "views" package will contain modules and classes making use of (and inheriting from) Melange's RequestHandler class to create views of web pages in response to user HTTP requests, and (3) the "logic" package will contain utility modules and functions.
=="modules"==
Melange maintains an attempted-but-imperfect separation between the code foundational to Melange itself and the code only needed for its (currently two) programs Google Summer of Code and Google Code-in. The foundational code for Melange itself is kept in the "logic", "models", and "views" directories of app/soc, and the code required for each program is kept under app/soc/modules/_program_name_.
=Dynamic Modules (How Melange Is Organized During Execution)=
Melange certainly _should_ have some lines of internal segmentation, fault-tolerance, and protection when running, but this is an area for future development.