Overview of the Oppia codebase（Oppia代碼庫總覽）

Oppia is built with Google App Engine. Its backend is written in Python, and its frontend is written using AngularJS.

Oppia是基於Google App Engine開發建設的。它的後臺是用Python編寫，前端是用AngularJS編寫。

The core核心

 

Most of Oppia's functionality is in the core/ directory, which is arranged as follows:

 大部分的Oppia功能都放置在core目錄中，範圍以下所示

Backend 後臺

One way to understand what this diagram means is to look at the lifecycle of a typical request. A user makes a request to the Oppia server by performing some action (like clicking a button) that causes some JavaScript code to issue a POST request. This request is made to a particular URL, which main.py matches to a handler in the core/controllers directory.

理解這張圖的含義的一種方式是透過一個典型請求的生命週期。一個用戶發出一個請求到Oppia服務器經過執行一些動做（像點擊了一個按鈕），這引發了某些JavaScript代碼處理一個POST請求。這個請求指向一個特定的URL，main.py匹配處理器在core/controllers目錄中。

Each controller is meant to be a thin layer that understands and validates the request, and then calls methods in core/domain to actually perform the computation/query, or change the state of the data on the server. The files in core/domain constitute the core functionality of Oppia and are where most of the logical operations occur.

每一個控制器意味着是一個薄層，用於理解和確認請求，而後調用在core/domain的方法來實際地執行計算或查詢，在服務器上更改數據的狀態。在core/domain目錄的文件組成了Oppia的核心功能，也是邏輯操做發生的地方。

In core/domain, there are generally two types of files: those whose names end in _domain.py, and those whose names end in _services.py. Files of the form *_services.py are mostly comprised of functions that act on data. On the other hand, files of the form *_domain.py define transient classes that represent Oppia objects (like explorations, states/cards, and so on); these classes are generally initialized using data from persistent storage, and are then operated on by functions in the *_services.py files.

在core/domain目錄，一般有兩種類型的文件：一種是以_domain.py結尾的文件，一種是以_services.py結尾的文件。以_services.py結尾的文件絕大多數包含操做數據的功能。另外一方面，以_domain.py結尾的文件定義了表明Oppia對象的臨時類（像探索，狀態/卡片，等等），這些類一般使用從永久存儲得到的數據進行初始化，而後被*_services.py文件中的功能操做。

Methods in the domain layer often need to access storage, memcache and other services provided by the application framework. All framework-dependent code (such as anything with a dependency on ndb or google.appengine) should go in core/platform. The platforms/models.py class provides an interface to these services, and refers to the correct classes based on what the underlying framework is at runtime. All files in the templates, controllers and domain layers should be independent of the underlying framework.

在domain層的方法常常須要訪問存儲，內存和其餘的應用程序框架提供的服務。全部框架依賴的代碼（如任何依賴於ndb或者GAE）應該放置在core/platform目錄中。platforms/models.py類提供了一個接口這些服務，引用到正確的類基於框架在運行時。全部的文件在templates、controllers和domain層應基於框架依賴。

The backend codebase is heavily tested. Tests are contained in *_test.py files next to the Python module they test. This naming convention allows them to be automatically detected and compiled into a test suite by Python's unittest module. For more information, see Running Tests.

後臺代碼庫是被嚴肅測試過的。測試包含在*_test.py文件指向到python模塊。這種命名習慣要求他們被自動檢測和編譯，在Python的unittest模塊測試套件。得到更多的信息，請看Running Tests.

Frontend 前端

The developer version of the frontend code is contained in core/templates/dev/head. (When Oppia is deployed, a core/templates/prod/head directory is also produced that contains minified versions of the code, but this is not generally of concern during development.) The frontend code contains the following sub-directories:。

前端代碼的開發者版本包含在core/templates/dev/head文件夾中（當Oppia被部署時，core/templates/prod/head/目錄被生成，包含了代碼的縮小版，可是這在開發期間通常是不關心的）前端的代碼包含在下面的子目錄中：

• admin: This provides the /admin page which exposes admin controls, e.g. for adding new moderators. admin目錄：它提供/admin頁，暴露admin控制，如添加新夥伴。
• components: This provides certain components, mostly for the editor. In particular there arerule_editor.html for the rule editor and visualizations.html for the state graph.components：它提供了必定的組件，主要是編輯器。特殊狀況下，有rule_editor.html對rule editor，visualizations.html 對狀態圖。
• css: Site-wide CSS. There may be other CSS blocks within individual HTML files.css：網站範圍的CSS.可能有其餘的CSS塊在各自的HTML文件。
• dashboard: The per-user notifications dashboard.dashboard：每一個用戶通知儀表盤。
• editor: The editor; this constitutes by far the largest and most complex section of code.editor：編輯器，這個有最大的和最複雜的代碼部分。
• error: Pages to display when a page cannot be loaded (e.g. due to unauthorised access).error：頁面顯示當一個頁面不能被加載（好比沒有權限訪問）。
• expressions: Code to parse and evaluate expressions (which may use parameters).expressions：代碼解析和評估表達式（可以使用參數）
• forms: Certain standard objects are used in various places throughout the website, such as rich text, lists and dictionaries. Code used to display editors for these objects is collected here.forms：表單，肯定的標準對象唄用在不少地方在整個網站，如，富文本，列表，字典。用來顯示編輯器的代碼收集在這裏。
• galleries: The gallery page that allows users to browse explorations.galleries：分類頁容許用戶瀏覽探索。
• moderator: The /moderator page that provides functionality for moderators.moderator：版主頁提供了對版主的功能。
• pages: Various static pages, such as the site guidelines.pages：大量的靜態頁，好比站點指南
• player: Services for the learner view. (The actual learner view templates are inextensions/skins.)player：學習者視圖服務（實際的學習者模板在extensiongs/skins）
• profile: Used when a new user registers, and to display usernames for logged-in users.profile：當一個新用戶註冊是使用，顯示登陸的用戶名。
• services: JavaScript handling the embedding of explorations in other websites, user warnings and other matters.services：JavaScript處理封裝的探索在其餘的站點，用戶警告和其餘內容。

Files generally come in triples of the form state_editor.html, StateEditor.js andStateEditorSpec.js. The spec file contains Karma unit tests for the JavaScript file.

文件通常以元組形式出現：state_editor.html，StateEditor.js 和StateEditorSpec.js。這個spec文件包含karma unit test 的javascript文件。

In general, within the HTML file, sections of the DOM are bound to particular JavaScript controllers. However, some JavaScript files cover multiple HTML files, and others provide general services and so have no HTML file.

一般，在html文件中，DOM的部分綁定到特定的JavaScript控制器。可是，一些JavaScript文件覆蓋了多個html文件，還有其餘的提供了通常的服務，所以，沒有html文件。

Extensions擴展

Oppia has a number of extension points that allow developers to augment its functionality, all of which are located in the extensions/ folder.

Oppia擁有大量的擴展點，容許開發者加強它的功能，全部的這些被放置在extensions/目錄。

There are several different types of extensions:

幾種不一樣類型的擴展：

• Objects represent object types that Oppia recognizes, such as NonnegativeInt, UnicodeString and Filepath. In general, they each come with an editor view, a readonly view, and a normalizer which tries to convert a Python object to the given type.Objects表明了Oppia識別的對象類型，好比非負整數、Unicode字符串、文件路徑。一般，它們每個跟着一個編輯器視圖，一個只讀視圖，和一個轉化器轉換Python對象到一個給定的類型。
• Rules allow learner answers to be classified, so that Oppia can provide appropriate feedback in response.Rules規則，要求學習者的回答被分類，以便Oppia能提供近似的反饋做爲迴應。
• Skins provide different user interfaces for the Oppia learner view.Skins提供不一樣用戶接口對於Oppia學習者視圖。
• Value generators are essentially functions which take some inputs and produce a single output. They are used when defining parameter changes: for example, they allow an exploration author to specify an exact value for the parameter, or a range of values, one of which is selected at random.Value generators值生成器是必須的功能，得到一些輸入和產生單一的輸出。他們被使用當定義參數變動：例如，他們要求一些探索做者指定一個準確的值對於參數，或者一個值範圍，其中一個被隨機選擇。
• Rich-text-editor extensions provide additional functionality for content that is shown to the learner. They are accessed via control buttons in the rich-text editor toolbar, and include things like videos, images, links and LaTeX math expressions.Rich-text-editor extensions富文本編輯器擴展提供了另外的功能對content被顯示給學習者。他們被訪問經過控制按鈕在富文本編輯器中，包含像視頻，圖像，連接和LaTeX數學表達式。
• Interactions, such as interactive maps and numeric input, allow the learner to submit an answer, which is then sent to the server for Oppia to respond to.Interactions交互，好比交互的地圖和數字輸入，要求學習者提交一個答案，這些被髮送到服務器得到Oppia的回饋。

Other files and folders其餘的文件和文件夾

• feconf.py contains various constants that are referred to by other backend files in the app.feconf.py包含大量的約束被其餘後臺文件所引用。
• The data/explorations folder contains sample explorations that are bundled with the Oppia distribution.data/explorations文件夾包含例子探索綁定到Oppia共享
• The scripts/ folder contains several utility scripts that automate processes like starting a development server, running tests, and deploying a copy of Oppia to a production server.scripts文件夾包含幾個工具腳本自動處理像啓動一個開發服務器，運行測試，部署Oppia的一個copy爲一個產品。

---

TODO: in the boxes in the diagram, consider giving a concrete example of a controller, domain model, etc. and walk up and down through the stack, maybe pointing to code examples. (This may be useful for new contributors who are not familiar with the codebase.)