V2 High Level Design Notes

• Contents

  1. V2 High Level Design Notes
  2. Introduction
  3. Ruby On Rails Resources
     1. On-Line Reference Material
     2. Books
  4. Source Code Management
     1. Repositories
        1. V2 Related git Repositories
        2. Creating a New git Repository
        3. Pushing a git Repository to the Git Server
     2. Use of Branches
  5. Application Services
     1. Logging
     2. Application Configuration
     3. Authentication
     4. JavaScript Libraries
     5. Internationalization
     6. Automated Unit and Integration Testing
     7. Background Process (Event Daemon)
     8. PDF File Generation
  6. Application Architecture
  7. User Access Modeling
     1. Definitions
     2. Requirements

Introduction

This section contains notes for the design and implementation of V2, in particular notes about how to use the technology stack.

Ruby On Rails Resources

On-Line Reference Material

1. Rails API documentation - http://api.rubyonrails.org

2. Rails Guides - http://guides.rubyonrails.org

Books

1. Ruby on Rails 3 Tutorial, by Michael Hartl - A beginning book with an emphasis on automated unit and integration testing with RSpec

2. The Rails 3 Way, by David H. Hansson - An advanced book with in-depth descriptions of most Rails related topics

   1. Section 11.20 - Internationalization using the I18n Ruby GEM

   2. Chapter 14.2 - Authentication using Devise
   3. Chapter 18 - RSpec

Source Code Management

1. Use git

Repositories

1. Server: git.softxs.ch
2. Directory: /home/bit/gitroot

V2 Related git Repositories

1. TODO mapps - Master Application Payment System Application source code

2. TODO v2 - V2 application code

3. TODO skeleton - Skeleton Application source code

4. TODO proto-ds - Darren Starsmore prototype

5. sample-app-ah - Alan Hodgkinson sample_app source code, from Hartl book

Creating a New git Repository

1. Repositories should have the suffix .git

2. Repositories should have group git and be group writable

The following example shows how to make a new git repository named new-name

• ssh git.softxs.ch
  
  cd /home/git/gitroot
  
  mkdir new-name.git
  chgrp git new-name.git
  chmod g+w new-name.git
  
  cd new-name.git
  
  git init --bare --shared
  
  echo 'Short one-line description of new-name project' > description
  
  vi config
  # add the following
  [gitweb]
     owner = Your Name

Pushing a git Repository to the Git Server

This needs to be done once to transfer your local repository to the git server.

Do the following from the root directory of your local git repository.

• git remote add origin user@git.softxs.ch:/home/git/gitroot/new-name.git
  git push origin master

Use of Branches

• TODO describe conventions for using branches

Application Services

Logging

1. Use Log4R

   • See: https://github.com/colbygk/log4r

   • Documentation: http://log4r.rubyforge.org

Application Configuration

1. Use rails_config

   • See: https://github.com/railsjedi/rails_config

2. For more about Rails application configuration:

   • http://guides.rubyonrails.org/configuring.html

Authentication

1. Use Devise

   • See https://github.com/plataformatec/devise

2. Consider the following supporting modules:

   1. CanCan - Integrates with Devise and provides useful authentication functions that can be used in .erb templates

      • See: https://github.com/ryanb/cancan

      • See: http://www.tonyamoyal.com/2010/07/28/rails-authentication-with-devise-and-cancan-customizing-devise-controllers

   2. OmniAuth - Which probably supports logins via Google+, Facebook, etc.

      • See: https://github.com/intridea/omniauth

3. General discussion of Rails recurity

   • See: http://guides.rubyonrails.org/security.html

4. Other references:

   • http://www.dixis.com/?p=332

JavaScript Libraries

Ruby on Rails uses unobtrusive JavaScript, which makes use of custom HTML attributes for binding HTML elements to JavaScript functions. This is done via special parameters to server-side calls to, which means that the you don't need to have script= attributes in your HTML.

1. Use jQuery - For DOM manipulation

   • See: http://api.jquery.com

   • See: http://docs.jquery.com

   • It is included by default in Rails 3.2 (formerly Prototype was used by default)

2. Use Backbone.js - For managing client-side collections of records with REST synchronization to the server

   • See: http://backbonejs.org

   • See http://documentcloud.github.com/backbone/docs/backbone.html

   • See: https://github.com/documentcloud/backbone

3. Use Underscore.js - Contains many useful general purpose utility functions. Required by Backbone.js

   • See: http://underscorejs.org

Internationalization

1. Use I18n

   • See http://guides.rubyonrails.org/i18n.html

   • See section 11.20 in Hansson book

Automated Unit and Integration Testing

1. Use RSpec - A Ruby GEM for specifying unit and integration tests

   • See https://www.relishapp.com/rspec/rspec-rails/docs

2. Use FactoryGirl - For generating test data

   • See https://github.com/thoughtbot/factory_girl

3. Use: Faker - A Ruby GEM, for generating fake/sample test data

   • See http://faker.rubyforge.org/

4. Resources:

   • Hansson book, Chapter 18

   • http://pure-rspec-rubynation.herokuapp.com

5. RSpec test specifications should include the tracking system bug number (e.g. 'BUG-4765') in the test description. This allows the bug to be specifically tested for using the RSpec -e parameter. E.g. rspec spec -e 'BUG-4765'

Background Process (Event Daemon)

• TODO

• See Chapter 20 in Hansson book. Suggested alternatives:

  1. Delayed Job https://github.com/collectiveidea/delayed_job

  2. Resque https://github.com/defunkt/resque (Requires Redis, and key-value storage mechanism)

  3. Rails Runner
• See general discussion at

  • https://github.com/blog/542-introducing-resque

  • http://wrangl.com/djvsrq

  • http://www.dixis.com/?p=335

PDF File Generation

• TODO

Application Architecture

• TODO describe the division between MAPPS and V2

User Access Modeling

Definitions

1. Library - an entity that contains multiple Projects

   1. A Library is the repository that manages user login, e.g. it authenticates users, typically via user login name and password (or LDAP, etc.)
      1. Contains a catalog of user names, login names and authorization information, e.g. encrypted passwords or links to LDAP or other authentication external authentication systems
   2. A Library does not contain user role information for individual projects
      1. Except that it is able to provide a list of links that jump to the home pages of the projects (in the library) that the user has access to
      2. If a user doesn't have any roles for a particular project, then they do not even see that the project exists
         1. This might be managed by a configuration variable, to allow implementation of a compeny-based systems which let all users see the names of all projects

2. Project - an entity that contains user data, e.g. documents, revisions, tasks, etc.

   1. Each project must belong to exactly one library
   2. A project contains:
      1. Project metadata, stored in the project's database
         1. Including user access rights for all the project's users
      2. A set of files (revision files, correspondence files, ZIP files, etc.) stored in a directory tree
      3. The metadata database and files of a project are never mixed between projects. This is to:
         1. Ensure customer data privacy
         2. Make it possible to make individual project backups

Requirements

1. A user has the same login credentials for all projects, he has access to, within a single library
2. A library dictates the user authentication policy, e.g. how user logins are validated, for all the projects that belong to it
3. A library has a landing page
   1. The landing page is the user login page for the all projects that belong to it
4. A library has administrative transactions for defining and managing users

   1. There are library users that have library administrator roles

   2. The library configuration sets the login security policy, e.g. password length, frequency of password changes, etc.
      1. Initially this will be via configuration variables
      2. Later this might be managed by online transactions available to the library administrators
5. Integrity of project metadata:
   1. All metadata for a project is stored in a single database
   2. Databases never contain metadata from multiple projects
6. Projects can be migrated between libraries
   1. This will initially be done using a manual procedure, e.g. shell and SQL scripts
   2. Later this could be automated
7. User roles for individual projects are managed within the projects

8. There are users that have project administrator roles within projects

   1. A project administrator manages user roles for a project
   2. The project administrator role is limited the project it is associated with
   3. A user might have project administrator rights in multiple projects

9. User roles for library and project administration do not include the ability to grant the roles to others, which are controlled by seperate grant library administrator and grant project administrator roles