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