Anatomy of Armstrong

Armstrong is a large project with a lot of moving parts. This document introduces you to all of those parts and helps you find your around the Armstrong ecosystem.

Terms in Armstrong

Access Level
An Access Level corresponds to a class of users. In the most common case, a site will have one Access Level that is free for every user and a single Access Level for paid subscribers.
An article represents one of the core objects inside Armstrong. It’s a title, body, summary, and additional meta data representing the articles on the site.
An Assignment defines a time period during which users posessing an Access Level are allowed to view a piece of content. They consist of a start date/time, an end date/time, a link to a particular piece of content’s access object and an Access Level
Backends are a callable that can be changed at run-time via configuration. These are generally used to provide flex-points where there are multiple ways to provide the same information.
A Content model provides a base class
Layout Templates
Layout templates are templates used by the {% render_model %} template tag. They’re found inside the <template_path>/layout/ directory and follow the pattern of <template_path>/<app_label>/<model>/<layout_name>.html.
A paywall is a function that wraps your content detail views and ensures that all users who view a piece of content have the required Access Level. They are configurable to provide a number of different responses to an unauthorized user including redirects, rendering different templates or raising an exception.
Related Content
Related content is a generic way to relate two completely separate models without either model having to know about the other. This is useful for generic code and is used throughout Armstrong. The flexibility comes with a slight performance hit, but most sites can cache their way out of the performance hit.
Sections provide a the foundation for a taxonomy for Django sites. Models opt-in to be included in sections. Each section has a series of items that it retrieves from the configured backend. This is generally combined with a well to allow “pinning” an item to the top of a section.
Wells allow you to schedule content to appear at a given place on your site for a given time. Wells are a particular Well Type and have zero or more Well Nodes.
Well Type
Well Types allow you to specify all of the wells you want to use. A Well Type can have any number of Wells created for it, but current Well for a given Well Type has a start date in the past and either no expiration date or an expiration date in the future.
Well Node
Well Nodes are the connection between a Well and any model within Django. They use a generic foreign key, but have some optimization to help remove some of the inherent inefficiency inside Django.

Component Structure

Anything that starts with armstrong.apps is considered a stand-alone application in the traditional Django sense. These occassionally have dependencies on other apps and components in the armstrong.core namespace. These are the main entry points to functionality in Armstrong.
Anything that starts with armstrong.core is considered part of the core Armstrong system and should generally be installed on any system that’s building on top of Armstrong. The number of models created by using armstrong.core components should be minimum. The only core components that install models are things which can only work with data stored.

Also known as “Hatband,” armstrong.hatband is Armstrong’s drop-in replacement for Django’s built-in django.contrib.admin. This provides some extra functionality in the admin interface and provides many custom widgets that are relied upon by various Armstrong apps.

Though Hatband does ship with some extra features that are meant to be used with Armstrong components, you can use Hatband within any Django project to create a better version of the Django admin.

armstrong.utils is the catch-all namespace. These are for entirely stand-alone components that might be used in multiple areas throughout Armstrong. These should have limited (if any) dependencies on other parts of Armstrong outside of other armstrong.utils components and Django itself.

Individual Components

A fresh installation of Armstrong installs the following components:

$ pip freeze | grep armstrong

The first package is the main Armstrong release. Each of the other components are explained below:

Provides a basic Article model for Armstrong
Provides a concrete implementation of the ContentBase model inside the armstrong.core.arm_content package.
Provides functionality around handling images inside Django.

Provides mechanism for relating content to other models

You can use armstrong.apps.related_content to link two separate models together through a GenericForeignKey for the source and the destination. You can further organize the relationship with RelatedType (think: “articles”, “images”, “external_links”, and so on) and all relationships are ordered.

Provides basic commands needed for Armstrong scaffolding
Provides a mechanism for restricting access to models inside Armstrong.
Provides a mechanism for restricting access to models inside Armstrong.

Provides layout related code for use in Armstrong and Django projects.

arm_layout provides you with tools to help streamline displaying content from within your application.


Provides the basic concept of sections within an Armstrong site.

You can use Section models to organize your content into a group. Sections can have a parent section to allow you to create a hierarchy. For example, the `Texas Tribune`_ has an Immigration section which in turns has Sanctuary Cities and Dream Act as children sections.

You are not limited to a hierarchical structure—you can create a flat structure as well.


Provides the basic content well code necessary for scheduling and arranging models inside Armstrong.

You can use wells to change the order of content. They are meant to be combined with querysets to allow your users to control what appears first in a list of content.


Provides the basic content well code necessary for scheduling and arranging models inside Armstrong.

You can use wells to change the order of content. They are meant to be combined with querysets to allow your users to control what appears first in a list of content.

Generic backend system to use throughout Armstrong

Table Of Contents

This Page