Architecture document

Note

This document is "superfluous" in the sense that the only documentation should be the running code itself in source and the acceptance tests (conversation section of each user story, and in the issue queue). However, it is sometimes useful to document decisions made in the course of project development, and this document strives to capture that.

Project genesis

• Executed express from parent directory to get basic scaffold

bash-3.2$ cd ..
bash-3.2$ express --version
2.3.11
bash-3.2$ express source

• Commit
  • https://github.com/victorkane/lit/commit/88921dc452f9b138fda36dd9ce412a7df5912194
• In my working copy root I ran npm install to install all dependencies into node_modules directory.

bash-3.2$ npm install
jade@0.12.1 ./node_modules/jade
connect@1.4.3 ./node_modules/express/node_modules/connect
mime@1.2.2 ./node_modules/express/node_modules/mime
qs@0.1.0 ./node_modules/express/node_modules/qs
express@2.3.11 ./node_modules/express

• I then include the node_modules directory in .gitignore and tested that express was working
  • https://github.com/victorkane/lit/commit/8b59b3983d25f50058d7e8260ec68c72c152238f
• I then merged in the express blog example to serve as functional scaffolding

From here on in, it's user story realization into analysis and design artifacts (see User Stories).

Frameworks

Although initially we were going with node only, without using express or grasshopper, etc., doing all the routing, etc., using custom modules, the decision was made to adopt the healthy principle of code re-use, standing on connect and express. That way we have community standard methods for auth, and many other things.

App packaging

For packaging our app, and the presence of package.json in our source root (originally marked as private when generated by express executable and then edited as additional dependencies are added) see this Express google group discussion: Should we use package.json for websites?

See Express quick start for our very initial code generation.

MVC considerations

An MVC approach: https://github.com/jasonmelgoza/express-blog/blob/master/app.js

An MVC approach is included in the Express example apps.

Available node modules and packages

In general, when searching for modules and packages, see Joyent's Wiki: https://github.com/joyent/node/wiki/modules

Also see NPM search

Front end

In terms of the front end, we must use a template engine. I am loath to use jade since I want designers to be able to work on this from their end, and they work with HTML. So I would prefer to use something like the vim zencode plugin and then use something like phptemplate or smarty or wicket. Decision not made yet. Set up as task.

Process (not really arch (should be config mgmnt) but one superfluous document is enough)

An agile approach, aiming to make the github repo be a self-documenting center for the project, based on Source, Issues and Wiki. Source and Wiki are repos. Issues can be backed up, cloned to another project, etc., via the GitHub API.

Roles and User Stories -> Prioritization into Issues Milestones -> Grab a User Story -> "Realization" (Analysis & Design) -> Main Acceptance Test versioned in the wiki, results in Issues (color coded for testing and associated with Milestones).

Issues filters and color coded labels, plus the built in issue milestones and open/closed issue status, do the job of rustic kanban board.

When the user story as an issue/task is work in progress, the first thing is that in the User story Conversation section, the nouns and verbs from the current text are listed, as a first "user story realization" analysis and design step.