-
-
Notifications
You must be signed in to change notification settings - Fork 11
Glossary & Resources
This page introduces concepts and tools/technologies relevant to ModularHistory.com's development.
See https://www.interaction-design.org/literature/topics/affordances. An application "affords" an action if it makes it obviously possible to take the action. We want ModularHistory to afford browsing, searching, filtering, etc.
An API, or Application Program Interface, is (conceptually) code that enables an application to respond to requests from other applications. In the context of web apps, an API could allow a web app to accept an HTTP request from another application, process the request, and send back data as a response (typically in JSON format).
One example of an API is the authentication API provided by Facebook, which enables any web application to allow users to sign in via Facebook. When a user attempts to sign in via Facebook, the web application sends a request to Facebook (using Facebook's API); Facebook authenticates the user; and Facebook sends back a JSON response (containing data like the authentication status, an access token, and an expiry time) to the web app, which then signs in the user.
ModularHistory's back-end Django application provides an API that enables ModularHistory's front-end Next.js application to dynamically request data from it. When the back-end Django app receives a request through its API, it queries ModularHistory's database (based on the request parameters); converts the resultant data (e.g., a list of historical occurrences) to JSON format; and sends the JSON response back to the front-end Next.js application, which processes the JSON and uses it to render the page that is displayed to the end user.
A container bundles an application's code with all of its software dependencies so that the application runs reliably in any computing environment (e.g., on a private server, in the cloud, or on a developer's laptop). For a slightly longer explanation, see "Containers 101: What are containers?" in https://cloud.google.com/containers. Containerization tools/softwares include Docker (used by ModularHistory) and LXC (also used by ModularHistory), among others.
In the case of Docker, each container is based on an "image": a lightweight, standalone, executable, immutable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries, and settings. An image becomes a container at runtime (i.e., when the image is run).
ModularHistory uses containers for everything. Our web server, Django application, Next.JS application, PostgreSQL database, Redis cache, etc. are all containerized.
A database is a persistent collection of structured data controlled by a database management system (DBMS). Databases can be relational (using SQL) or non-relational (NoSQL).
ModularHistory uses a PostgreSQL relational database to store its collections of historical occurrences, quotes, sources, etc.
Typically, developers interact with a database through an ORM.
In the context of software development, a framework is a library of code that acts as a platform for developing applications. Examples of frameworks include Django (a Python web development framework) and Next.js (a JavaScript web development framework based on React), both of which are used by ModularHistory.
Typically, a framework provides a skeleton for an application, and developers then add code to the skeleton. So, all projects that are based on the same framework can be expected to share a similar code structure.
An IDE (or integrated development environment) is a software application that makes programming easier by consolidating tools for editing source code, building executables, debugging, and other common activities of software development. Examples of IDEs include PyCharm and Visual Studio Code.
MVC is a software design pattern that divides program logic into models, views, and controllers.
Models are classes that control the structure and behavior of the objects the application works with (in ModularHistory's case, users, historical occurrences, quotes, sources, etc.) and the way those objects are stored in the database.
Views define how information (typically contained in model instances) is presented to consumers, e.g., in HTML or JSON responses to users/clients. They can be thought of as response templates.
Note: In the Django framework, views are referred to as "templates."
Controllers handle the application logic; they accept input/requests from users/clients, perform whatever processing is needed, and use views to render the response that is delivered to the user/client.
Note: In the Django framework, controllers are (somewhat confusingly) referred to as "views."
An ORM is simply a code library that enables us to interact with a relational database using familiar object-oriented code (e.g., Python) rather than SQL. For a more detailed explanation, see https://www.fullstackpython.com/object-relational-mappers-orms.html. Since ModularHistory's back end is powered by Django, our application code uses the Django ORM to interact with ModularHistory's database. (So, we usually don't have to work with raw SQL.)
A single-page application (SPA) dynamically rewrites a single web page with new content from the web server, rather than loading entirely new pages. This generally improves page-load times and makes the app feel more like a native app than a traditional website. Examples of SPAs include GitHub, Facebook, and Google Maps: when you click internal links in these web apps, they use JavaScript to request new content and load that content onto the existing page, rather than requesting entirely new pages. Front-end JavaScript frameworks such as React (which was developed by Facebook) are designed primarily to support single-page applications.
ModularHistory is in the process of being converted from a multi-page application (using pages rendered by Django) to a single-page application (using a single page rendered by React/Next.JS, supported by a Django API).
For a longer explanation of single-page applications vs. multiple-page applications, see https://medium.com/@NeotericEU/single-page-application-vs-multiple-page-application-2591588efe58.
See https://www.educative.io/edpresso/what-is-server-side-rendering.
Django is a popular Python web development framework with excellent official documentation. Django follows the MVC pattern, although it uses slightly different terminology: in Django, views are referred to as "templates," and controllers are referred to as "views."
ModularHistory was originally built as a pure Django web application. However, to gain the UX benefits of an SPA and support greater interactivity, ModularHistory is now being split into a back-end application powered by Django and a front-end application powered by Next.JS/React. Many pages served by ModularHistory are still rendered entirely by Django, but eventually, most pages will be rendered by Next.JS. When a ModularHistory page is rendered by Next.JS, the page's JavaScript makes requests to ModularHistory's back-end API (powered by Django REST Framework) to retrieve and/or perform operations on the data.
If you are new to Django, consider completing the official tutorial to get a feel for how the framework works.
ModularHistory's back end uses Django models to define the structure and behavior of objects like users, occurrences, quotes, sources, etc. When we want to work with new types of information, we may have to create new models; when we want to add new fields (attributes) to existing structures, we have to modify the model classes. See https://docs.djangoproject.com/en/3.1/#the-model-layer.
ModularHistory's back end uses the Django ORM to interact with its PostgreSQL database. Resources:
Django REST Framework is a library for building web APIs. We use DRF to build out the API that enables pages rendered by Next.JS to access ModularHistory's data.
Docker is a set of tools/software for containerizing applications. ModularHistory's Next.JS application and Django application run in Docker containers based on Dockerfile.react and Dockerfile.django, respectively. All of the services that support the back end (PostgreSQL database, Redis cache, etc.) run in containers based on public images.
Docker Compose is a tool for running multiple containers together. See ModularHistory's docker-compose.yml.
JavaScript is the programming language of the web. It is primarily intended for client-side execution: it runs in users' browsers. JavaScript runs in every web browser, out of the box. Every interactive web page uses JavaScript. If you are new to JavaScript or want a refresher, consider taking a look at the following resources:
- https://www.w3schools.com/js/default.asp
- https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps/What_is_JavaScript
- https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript
Next.JS is a React framework that provides several useful features, including client-side routing and server-side rendering, out of the box. If you are new to Next.JS, first take a look at React, then consider using the following resources to ramp up:
Nginx is open-source software for web serving, reverse proxying, caching, load balancing, and more, with better performance than Apache (older open-source software for web servers). ModularHistory.com uses an Nginx server to:
- serve static files (CSS, JS, images, etc.)
- reverse proxy the back-end (Django) and front-end (Next.JS) servers so that they can respond to HTTP requests
Nginx configuration files for ModularHistory's development and production environments live in config/nginx.
PostgreSQL, aka Postgres, is "the world's most advanced open-source relational database."
Generally, we don't have to deal with Postgres directly; we use the Django ORM.
Python is an object-oriented programming language that is designed to be easy to read and easy to learn. Django, the web framework used for ModularHistory's back end, is a Python web framework. If you are new to Python, consider using the following resources to ramp up:
React is a widely used JavaScript library for building user interfaces and/or reusable UI components. It is the basis of Next.JS, the framework that ModularHistory uses for its front end. If you are new to React, consider using the following resources to ramp up: