= V2 High Level Design Notes =

[[V2Master]]


  <<TableOfContents>>

= 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
 1. '''Rails Guides''' - http://guides.rubyonrails.org

== Books ==

 1. '''''[[http://ruby.railstutorial.org/ruby-on-rails-tutorial-book|Ruby on Rails 3 Tutorial]]''''', by Michael Hartl - A beginning book with an emphasis on automated unit and integration testing with '''RSpec''' - 
 1. '''''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
    1. Chapter 14.2 - Authentication using Devise
    1. Chapter 18 - RSpec

= Source Code Management =

 1. Use '''git'''

== Repositories ==

 1. Server: git.softxs.ch
 1. Directory: /home/bit/gitroot
 1. HTTP access: http://git.softxs.ch/projects

=== V2 Related git Repositories ===

 1. '''''TODO''''' '''mapps''' - Master Application Payment System Application source code
 1. '''''TODO''''' '''v2''' - V2 application code
 1. '''''TODO''''' '''skeleton''' - Skeleton Application source code
 1. '''''TODO''''' '''proto-ds''' - Darren Starsmore prototype
 1. '''sample-app-ah''' - Alan Hodgkinson sample_app source code, from Hartl book

=== Creating a New git Repository ===

 1. Repositories should have the suffix '''.git'''
 1. 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

 1. '''''TODO''''' define the using of log levels '''DEBUG''' < '''INFO''' < '''WARN''' < '''ERROR''' < '''FATAL'''

=== Configuring Logging ===

 1. Add the following to '''Gemfile''', and the run ''bundle install''
    {{{
gem 'log4r'
    }}}

 1. Add the following to '''config/application.rb'''. Add the line to the ''very end'' of the file 
    {{{
require File.expand_path(File.dirname(__FILE__) + "/log4r_init.rb")
    }}}

 1. Create the file '''config/log4r.yml''' with the following contents: [[attachment:log4r.yml]]

 1. Create the file '''config/log4r_init.rb''' with the following contents: [[attachment:log4r_init.rb]]   


== Application Configuration ==

 1. Use '''rails_config'''
    * See: https://github.com/railsjedi/rails_config
 1. For more about Rails application configuration, in general terms:
    * http://guides.rubyonrails.org/configuring.html

Details:

 1. YAML based configuration file
 1. Can overrides/overlay configuration based on environment
 1. Supports local configuration files to allow easy tweaking of installations and deviations from checked in configuration files
 1. Supports embedded ruby in the yml file. For example:
     {{{        
filename : <%= "#{Rails.root}/log/#{Rails.env}.log" %>
     }}}
 1. Easy to access config variables. E.g. Settings.SXS.certsfile and/or Settings[‘’SXS’’][‘’certsfile”]
 1. Supports nested configuration. This allows all application configuration to be pushed down under ‘’SXS” for instance to avoid conflicts with any other settings


== HTML Templates ==

 1. Use '''erb''' - Built into Ruby

Alternatives to investigate:

 1. '''Haml'''
 1. '''Slim'''

== CSS Templates ==

 1. '''''TODO'''''

Alternatives to investigate

 1. '''CASS'''
 1. '''SCSS'''

== Database Server ==

 1. Use '''MySQL''' - Preferably for all environments

=== Configuring MySQL ===

 1. Add the following to your '''Gemfile'''

    {{{
gem 'mysql2'
gem 'bcrypt-ruby', '~> 3.0.0'
gem 'therubyracer', :platforms => :ruby
    }}}

 1. Edit the '''config/database.yml''' file, and add configuration like the following for each environment:

    {{{
development:
  adapter: mysql2
  encoding: utf8
  reconnect: true
  database: dbname
  pool: 5
  username: dbuser
  password: dbpasswd
  socket: /opt/local/var/run/mysql5/mysqld.sock
    }}}

Notes:

 1. In the Gemfile:
    1. The mysql2 Gem should be added at the top of the and be available for all environments
    1. The bcrypt-ruby and therubyracer Gems are probably already in the Gemfile and just need to be enabled
       1. The bcrypt-ruby Gem is needed for encrypting the MySQL password. If you get an error like the following then it may be rcaused by the Gem being missing
       {{{
#<Mysql2::Error: Access denied for user 'root'@'localhost' (using password: NO)>
       }}}
       1. The therubyracer Gem is (apparently) needed by the mysql2 Gem. If you get a Java``Script related error, then it might be related to this

 1. In the config/database.yml file
    1. Set the appropriate database name. Use different names for each environment
    1. Set the appropriate database user ('''''TODO''''' probably 'root'.. to be investigated) and password
    1. Note that 'rake db:reset' actually sets the database password for the db user, which may cause surprises
    1. If you get server timeouts, make sure 'reconnect' is set to true

 1. You can create a new project that uses MySQL as the default database:
      {{{
rails new project-name -d mysql
      }}}

== Authentication ==

 1. Use '''Devise'''
    * See https://github.com/plataformatec/devise
 1. Consider the following supporting modules:
    1. '''Can``Can''' - 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
    1. '''Omni``Auth''' - Which probably supports logins via Google+, Facebook, etc.
       * See: https://github.com/intridea/omniauth
 1. General discussion of Rails recurity
    * See: http://guides.rubyonrails.org/security.html
 1. Other references:
    * http://www.dixis.com/?p=332

== JavaScript Libraries ==

Ruby on Rails uses '''unobtrusive Java``Script''', which makes use of custom HTML attributes for binding HTML elements to Java``Script 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)
 1. 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
 1. 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
 1. Use '''Factory``Girl''' - For generating test data
    * See https://github.com/thoughtbot/factory_girl
 1. Use: '''Faker''' - A Ruby GEM, for generating fake/sample test data
    * See http://faker.rubyforge.org/
 1. Resources:
    * ''Hansson'' book, Chapter 18
    * http://pure-rspec-rubynation.herokuapp.com

 1. 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'''''

 1. See Chapter 20 in Hansson book. Suggested alternatives:
    1. Delayed Job https://github.com/collectiveidea/delayed_job
    1. Resque https://github.com/defunkt/resque (Requires Redis, and key-value storage mechanism)
    1. Rails Runner

 1. 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
    1. 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
       1. 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

 1. '''Project''' - an entity that contains user data, e.g. documents, revisions, tasks, etc.
    1. Each project must belong to exactly one library
    1. A project contains:
       1. Project metadata, stored in the project's database
          1. Including user access rights for all the project's users
       1. A set of files (revision files, correspondence files, ZIP files, etc.) stored in a directory tree
       1. The metadata database and files of a project are never mixed between projects. This is to:
          1. Ensure customer data privacy
          1. 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
  1. A library dictates the user authentication policy, e.g. how user logins are validated, for all the projects that belong to it
  1. A library has a landing page
     1. The landing page is the user login page for the all projects that belong to it
  1. A library has administrative transactions for defining and managing users
     1. There are library users that have ''library administrator'' roles
     1. 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
        1. Later this might be managed by online transactions available to the library administrators

  1. Integrity of project metadata:
     1. All metadata for a project is stored in a single database
     1. Databases never contain metadata from multiple projects
  1. Projects can be migrated between libraries
     1. This will initially be done using a manual procedure, e.g. shell and SQL scripts
     1. Later this could be automated
  1. User roles for individual projects are managed within the projects
  1. There are users that have ''project administrator'' roles within projects
     1. A project administrator manages user roles for a project
     1. The project administrator role is limited the project it is associated with
     1. A user might have project administrator rights in multiple projects

  1. 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