Front End Architecture

Notebook and Session Model

A Notebook Model (stored in a .bkr file) has three main parts:

1. cells and their relationships (including the layout, tag map)
2. evaluators
3. the notebook namespace, where the "beaker" object is stored, enabling autotranslation.

When a notebook is loaded, these two parts will be owned and managed by 2 services (managers) respectively:

• cells and their relationships are owned by Notebook Cell Model Manager, the manager also provides method for cell operations (e.g. move cell).
• evaluators are owned by Evaluator Manager

Additionally, when a notebook is loaded, a correspond Session is created. In addition to the information stored in the notebook, there is other meta information that need to be managed. Essentially, a Session needs:

• Session Meta-data Manager, which holds information like: path, path type, file type … etc. as well as exposes methods like getSaveFunc
• Notebook Model Manager, which is a thin wrapper around aforementioned (adding only methods like: isEdited):
  • Notebook Cell Mode Manager
  • Evaluator Manager
• (There maybe should be a 3rd category of session data that needs to be preserved, that is, the states of UI, not sure if everything there goes to the notebook)

A Session Model is a data structure that composes of information needed for restoring a session, which is basically:

• Session meta info, which is managed by Session Meta-data Manager
• Raw notebook model, this is the notebook model read from file, which is managed by the Notebook Model Manager

Differentiate “Evaluate” manager and “Evaluator” manager, and “Evaluate Plugin” manager:

• Evaluate Manager is in bkApp right now and needs to be separate out into a stand alone service. It should be the central control of evaluation status/progress and the queue(s) of tasks to be evaluated.
• Evaluator Manager is the manager managing which evaluators have been created and are available right now.
• Evaluate Plugin Manager is the manager that keep track of which plugins has been loaded.
• Code cells should depends on Evaluate Manager (but not Evaluator Manager) in that code cells send the Evaluate manager jobs (code and output placeholder) to be queued and evaluated.
• Evaluate Manager should depend on Evaluator manager in that upon evaluating a job, it asks the Evaluator Manager to locate the corresponding evaluator needed by the job.
• Evaluator Manager depends on Evaluate Plugin Manager to request constructors for creating new evaluators.
• bkApp when route changes, opening a notebook should reset Evaluate and Evaluator manger (but not Evaluate Plugin manager) so that:
  • It resets Evaluate Manager so that in-progress evaluation(s) (if any) are interrupted, the queue is emptied.
  • It resets Evaluator Manager so that all evaluators are destructed properly (unsubscribe channel, close socket … )

Beaker App

A Beaker App can be viewed as made up by two kinds of things:

• Views, (angular controllers)
• Services, (angular services, singletons)

Views

Views are the minimal code needed for setting up scope and controllers that interfaces(2-way binding, watch and update both view and model) a fraction of the raw notebook model and its corresponding UI component. The two main apps:

• The Control Panel
  • bkControl
• The Beaker Main Notebook Viewer (Remember, there could be other viewers that take the same notebook model and present it in other layouts in the future)
  • bkApp, interfaces the:
    • whole notebook, including cells and tag maps and evaluators (the evaluators used by and thus created for the notebook, not the 3 Evaluat* managers).
      • consider moving this to bkNotebook
    • plugins, loading plugins (menu, cell menu), display plugin settings in the UI. Take user action event in ui and update plugins.
  • bkNotebook, interfaces the root cell model
  • bkSectionCell, interfaces a section cell model
  • bkCell, bkCodeCell, … interfaces a cell model
  • ...

Note that the views here are the views for the notebook itself, this does not include things like evaluator/plugin manager UI, file chooser, etc, which are relatively isolated and will be owned by the corresponding services.

Take a closer look at bkCodeCell as an example:

• bkCodeCell should depends on Evaluate Manager to perform evaluate()
• bkCodeCell, upon ‘insert(After)’, should depends on Notebook Cell Model Manager to update the notebook raw model.

Services

Services include:

• Notebook parts managers (mainly the ones mentioned above), i.e:
  • Session Meta-data Manager
  • Notebook Cell Mode Manager
  • Evaluator Manager
• App specific services:
  • For both bkControl and bkApp (one for each)
    • Menu Plugin Manager
  • bkApp Viewer specific services:
    • Evaluate Manager
    • plugin managers:
      • Evaluate Plugin Manager
      • Cell Menu Plugin Manager
    • Output Display Manager
• Global Services
  • Default/User config Manager
  • Routing Manager
    • File Opener Manager (e.g. getOpener(“file”))
      • menu plugin can register file openers
    • Session Loader/Unloader
  • Recent Menu Manager
  • UI Focus Manager
  • Code Mirror Central Manager
  • Logging Manager
  • Isolated UI Components
    • Modal Dialog
    • FileChooser
    • Stdout/Stderr
    • Plugin Setting UI
  • Global State Tracker (e.g. isDebugging?)
  • Level utilities
    • General Utils
    • Angular Utils
    • Beaker Utils

bkCore

The global services are bundled in a single service bkCore. View controllers depends on notebook parts manager and app specific services directly while depends on global services via bkCore.

bkHelper

• is essentially the combination of ALL services, that is the notebook parts managers, plus app specific services plus bkCore.
• is the only service exposed through a global variable. which should be the end point of the dependency graph, that is, it should depends on everything (directly or indirectly) and nothing should depends on it.
• is the only service that all plugins use or depend on.