The Webmaker code is spread across a large number of repositories, modules, libraries, apps, and web sites. Trying to locate the code for a particular part of Webmaker can be a challenge. The following is a high level introduction to the code.
Technical Overview of Webmaker
Users typically begin at https://webmaker.org, and so our discussion will start there too. The webmaker.org site has four main features, including:
- allowing users to access Webmaker tools, including Popcorn Maker, Thimble, and X-Ray Goggles.
- allowing users to search for and browse various "makes," which are objects in the Make API made with one of the Webmaker tools, or by a third-party web tool.
- allowing users to create or find Webmaker Events, using a Google Maps driven sub-application often referred to as Webmaker Events or just Events.
- allowing users to create a Webmaker (and by extension, Persona) account.
Beginning with account creation, webmaker.org (and other tools via the common navigation header) connects to the Login server (i.e., login.webmaker.org). Webmaker uses Mozilla Persona for user authentication and sign-in. Additional code has been written on top of Persona to allow single-sign-on across all Webmaker tools and sites (e.g., webmaker-sso). When a new Webmaker account is created, the Persona email is stored, along with extra information about the user (e.g., name, email notification preferences, etc.). The username is also used to create a new (virtual) domain on makes.org (or mywebmaker.org in our staging environment). For example, user donald would get donald.makes.org. All published makes for this user (i.e., things created with Webmaker tools) will be available at username.makes.org/something. The choice to use makes.org for hosting user content was done in order to provide origin-isolation from our Webmaker apps and code, which lives on webmaker.org (or mofostaging.net in our staging environment).
The username.makes.org page is actually the Webmaker Profile app. Here all the user's makes are displayed, along with various widgets for creating new UI components in the profile. The Profile app, like webmaker.org, uses the Make API and Login servers in order to find all the makes for a particular user--in fact most Webmaker apps work this way. Communication between the Make API, Login server, and other node apps happens over HTTP APIs within in the production (or staging) deployment network.
Users create "makes" using Webmaker tools. All tools allow authenticated Webmaker users (i.e., must have account in the Login server) to publish what they make. Publishing means a number of things. First, user generated content from the tools (e.g., HTML) is saved to an Amazon S3 bucket. A unique URL is also created, such that users can access their content again via their makes.org domain. The Make Valet app provides the routing and logic to map a URL to the content in S3, and common UI for details about a make (i.e., metadata from the Make API). Second, publishing means inserting a record into the Make API, which includes metadata about the make, like URL, date info, which tool was used, tags, etc. The Make API indexes makes using Elastic Search so that they can be found again easily.
A Tour of Webmaker Code
For the most part, Webmaker code lives in one of many repositories hosted under the Mozilla Github Organization. We also contribute to a number of upstream projects, not all of which are listed below (e.g., node.js modules or libraries we use, but don't maintain directly). There are a few exceptions, but we try to graduate repositories we rely on to the Mozilla Organization instead of hosting them under individual github accounts. For more information about any of these repositories, you are encouraged to consult each their READMEs.
- Webmaker.org: https://github.com/mozilla/webmaker.org - the node.js app and front-end code for https://webmaker.org, including things like Events and the Web Literacy Standard.
- Thimble: a friendly real-time updating code editor, includes:
- thimble.webmaker.org: https://github.com/mozilla/thimble.webmaker.org - the node.js app and main/shell front-end code.
- friendlycode: https://github.com/mozilla/friendlycode/ - the code editor used by Thimble
- slowparse: https://github.com/mozilla/slowparse - an HTML5 parser with extra metadata and error handling
- togetherjs: https://github.com/mozilla/togetherjs/ - TogetherJS real-time collaboration library
- Popcorn Maker: a web-based media editing tool, includes:
- popcorn.webmaker.org: https://github.com/mozilla/popcorn.webmaker.org - the node.js app and front-end for Popcorn Maker
- popcorn.js: https://github.com/mozilla/popcorn-js - the Popcorn.js HTML5 media library
- mediasync: https://github.com/mozilla/webmaker-mediasync - sync/query services for media APIs
- X-Ray Goggles: https://github.com/mozilla/goggles.webmaker.org - the node.js app and front-end bookmarklet code for X-Ray Goggles, a tool for visually exploring and changing the underlying structure of web pages
- Login (aka login.webmaker.org): https://github.com/mozilla/login.webmaker.org - node.js single-sign-on (SSO) server and identity provider for Webmaker apps, as well as front-end UI components for authentication, based on Mozilla's Persona
- MakeAPI: https://github.com/mozilla/makeapi - node.js metadata server for storing and indexing information about "makes" (e.g., things made on the web with Webmaker tools or 3rd party tools).
- Make Valet: https://github.com/mozilla/make-valet - node.js app for hosting information about makes (e.g., Make Details).
- Webmaker Profile: https://github.com/mozilla/webmaker-profile - node.js app and front-end for username.makes.org profile pages, includes:
- webmaker-profile-service: https://github.com/mozilla/webmaker-profile-service - RESTful API for profile
- Common Node/JS Modules used by many Webmaker apps and code:
- webmaker-sso: https://github.com/jbuck/node-webmaker-sso - Single-Sign-On solution for Persona
- makeapi-client: https://github.com/mozilla/makeapi-client - node.js and browser-js client lib for communicating with the MakeAPI
- webmaker-i18n: https://github.com/mozilla/node-webmaker-i18n - Localization and Internationalization code for node.js and HTML.
- webmaker-loginapi: https://github.com/mozilla/node-webmaker-loginapi - client lib for accessing Login server from node.js
- webmaker-postalservice: https://github.com/mozilla/node-webmaker-postalservice - Webmaker mailer for apps requiring email services
- mox-server: https://github.com/Pomax/mox-server - mock implementation of the Amazon S3 service in node.
- webmaker-analytics: https://github.com/mozilla/webmaker-analytics - Webmaker utilities for analytics
Webmaker Style Guide
Anyone working on Webmaker's front-end, or otherwise altering aspects of user-facing UI/UX should be aware of the Webmaker Style Guide. The Style Guide provides important information about Webmaker's design philosophy and branding, typography, logos, colours, thumbnails, etc.
For Webmaker Logos and other branding marks, see http://www.mozilla.org/en-US/styleguide/identity/webmaker/branding/
Webmaker is a global product, focused as much on non-English speakers as English, and used around the world. We have localized our apps and tools using a mix of server-side and client-side localization. The details about how we do this is available in the Webmaker I18N README.
Even if you don't plan to translate strings, you'll probably have to make yourself aware of how localization works, since any change to code that touches the front-end or UI will likely trigger an l10n change. See the workflow section for more details.