Skip to content

Colibri architecture overview

Jump to bottom
Alexandre CUER edited this page Aug 30, 2019 · 4 revisions

colibri architecture overview

folders controller

The list json method is intended to assure a fluid navigation experience to the user within the files/folders system. This experience is what we call the "ajax browsing system"

The list method renders the folder datas and all datas describing related objects connected to the folder : subfolders, assets, shares, feedbacks

When given no id, the list method also renders the folders shared to the current user by others

This method is low cost, using a few join requests and once the has_shared_access? method of the user model (which is indeed costly)

The browse method is :

  • half a json API method, used on the fly by the ajax browsing system to regenerate a folder fragment in order to correctly indicate its status (shared or not)...Indeed, a status modification may occur after a user has added or deleted shares....this status verification burns a single SQL request and can be easily achieved with folders metadatas (stored in field lists)
  • half a classic rails method, leading to the ajax browsing system, via the browse.html.erb of views/folders, or to the old browsing style navigation (browse?oldstyle=1) through the show.html.erb

The old navigation system uses breadcrumbs and relies on the show method, which outputs the current_folder record to show.html.erb

  • If the current_user already expressed a feedback, the show method redirects to the corresponding satisfaction_path.
  • If the folder is polled, shared to the current_user who has not recorded a feedback, the show method renders the new satisfaction form

This is the "classic browsing system" for public users.

Please note there is no new satisfaction form integrated to the ajax browsing system. At this stage, the ajax browsing system is intended to private users.

For folder creation, the controller offers 2 options :

  • the classic rails create method
  • the json method create_folder

They both create a new folder record and use the initialize_meta method of the folder model to initialize the list field

Things are similar as far as folder update is concerned :

  • the update_folder method is used in ajax views. It uses the calc_meta method from the satisfaction method to update meta field of all related feedbacks...it does not modify the folder metadatas....
  • the update method is a classic rails method...it should also use the calc_meta method from the satisfaction method...it checks if folder case number has already been used for another folder (no real interest ?)

folder model

This model contains 4 methods to deal with folders metadatas :

  • initialize_meta
  • calc_meta
  • get_meta
  • legacy which returns the id of the user being granted the folder as swarmed (when a private user usr2 creates a subfolder B in a folder A for which he was granted a share by a user usr1, we consider B as a folder swarmed to usr1 : usr1 has a superuser access to folder B)

examples of folder metadatas:

  • {"shares":[87,89,86,88,92,93],"satis":[]}
  • {"shares":[76,74,75,77],"satis":[],"swarmed_to":31}
  • {"shares":[63],"satis":[21]}

The method process_share_emails of the folder model checks if folder belongs to current_user, then downcases all the emails given in params. It searchs in the shared_folders table if the folder already owns share(s) for the downcased email(s)....

Such a request can be achieved with the following piece of code :

current_user.shared_folders.where("LOWER(share_email) = ? and folder_id = ?", email_to_search, self.id)

which produces a SQL sentence of this type :

SELECT "shared_folders".* FROM "shared_folders" WHERE "shared_folders"."user_id" = $1 AND (LOWER(share_email) = 'alexandre.cuer@wanadoo.fr' and folder_id = 45) [["user_id", 4]]

Actually, the complete piece of code is :

if Rails.configuration.sharebox["downcase_email_search_autocomplete"]
    email_to_search=email_to_search.downcase
    share=current_user.shared_folders.where("LOWER(share_email) = ? and folder_id = ?", email_to_search, self.id)[0]
else
    share=current_user.shared_folders.find_by_share_email_and_folder_id(email_to_search,self.id)
end

If share is nill, the method creates the new share and updates the folder metas via the calc_meta method of the folder model

The folder model also includes a move method which is intended to be the core method for folder moves/drag'n'drops operations in the future....2 API json methods are implemented in the admin controller using this move method....work in progress

ajax browsing system

The navigation in the files/folders system uses initially the list and getpolls methods to feed the root tree view and the polls javascript list, but others json methods are called while the user deeply explore the tree :

  • browse?id=folder_id to regenerate fragments
  • getshares/folder_id, when a new share is created, to update the shares'list
  • users?melfrag=sometext to achieve autocompletion on users emails
  • update_folder
  • share
  • delete_share/folder_id/share_id
  • create_folder
  • delete_folder/folder_id
  • upload_asset
  • delete_asset/id

shared_folders controller

Dedicated to share management and accessible only to registered users, this controller contains 4 json API methods, used by the ajax browsing system :

  • contact_customer, which begins by checking if the current_user is the folder owner. If yes, it scrolls through the shared_folders table in search of a share corresponding to the directory number and the downcased email given in params. If all tests are passed successfully, it uses the email_customer method from the folder model to send the email
  • getshares, which renders a json list of shares for a given folder
  • share, which relies on the process_share_emails method of the folder model
  • delete_share, which calls the calc_meta method of the folder model after a share has been successfully destroyed

The index method is a "reach new version" method....it launches manually the folders metadatas updates (stored in field list)

All others methods are classic REST methods, deprecated but still usable via classic rails routes (browse?oldstyle=1)

satisfactions controller

The specificity of this controller is to permit, via its create method, to record satisfactions IN and OUT of the files/folders system

Out of the files/folder system means whitout connecting things to an online deliverable, hosted in a folder shared to registered customer ie a public user recorded in the User table

We call this "free surveying of unregistered clients". It means we can survey client emails that are not recorded in the user table.

Once the email of a unregistered client has been validated (after he has successfully answered to a free survey) he is recorded in the client table which is used for autocompletion tasks in the free surveying dashboard

so actually, colibri has a user table and a client table and maybe this bias is too complicated......

On the other hand, when recording a feedback related to folder, the create method uses the calc_meta method of the folder model in order to store the new feedback number in the folder metadatas json field...

The satisfactions controller is basically a classic rails controller leading the user to classic rails views (erb.html)

Nevertheless, it has got 4 json API methods : run, index, json, freelist

  • the run method is a complex filter on satisfactions records. It uses the private function prepare and some methods from the poll model : csv, count_sent_surveys and stats
  • the index method renders a json output of all satisfactions feedbacks for all polls
  • the json method renders a json output of a single feedback given its id
  • the freelist method renders for the current user all feedbacks he has collected out of the files/folders system. This json request is used to generate the bottom of the free surveying dashboard, where a list of clickable project ids permits to open a modal window with a nice output for each feedback, using coloured stars

the private function prepare creates the core of the SQL request. It validates the date/time range before constructing the request. It validates also the ncap parameter (to track feedbacks with dissatisfactions...) by converting it to an integer. It also permits to filter on groups or on the project manager email by giving a fragment or a full email to search

the private arrange function is responsible for producing outputs in a human readable json format. It is used by both run and index methods

The private gentitle function is used only once in the create method when dealing with a free survey. It generates the so-called meta case_number from the survey parameters (description, client_mel, by). It is a very basic function.... When dealing with a survey in the files/folders system, we use the calc_meta method of the satisfaction model, which is responsible for producing the case_number meta in the classic situation, requesting necessary datas in the folders and users records. calc_meta called without any arguments burns three SQL requests. Sometimes and to go faster, calc_meta is called with 2 arguments : the folder record and the client/user record. In that case, it burns only one SQL record (to find the folder owner email) and is very similar to gentitle

Examples of API queryings whith the run method:

/satisfactions/run/2?groups=DirCE/DLCF&start=2019-02-23&end=2019-08-24&csv=1

/satisfactions/run/2?start=2019-02-23&end=2019-08-24&email=florence

/satisfactions/run/2?ncap=2

polls controller

classic rails controller, mostly restricted to admins for polls management

a getpolls method is open to all registered users, rendering a json output of all polls or a json list of poll ids for which the user has launched free surveys.

surveys controller

a classique json controller exploited by a single ajax view, only for team members : the free surveying dashboard

a member of the team can :

  • create new surveys (create method)
  • destroy the surveys he has created if still pending (destroy method)
  • list pending surveys for the whole team, for a specific group, with a filter on a specific date/time range, and list, poll by poll, his personal feedbacks or all feedbacks collected out of the files/folders system. For pending surveys, output is json only. For answers, output is csv (index method which uses the csv method of the poll model)
  • send mel associated to pending surveys for the whole team (show method whith an email params - email is not validated it should be even though a pre-validation is actually done in the ajax view)
Clone this wiki locally