Skip to content

Architecture

Jump to bottom
Atul Varma edited this page Aug 2, 2019 · 19 revisions

Core principles

The JustFix.nyc Tenant Platform (sometimes called "tenants2") was designed with the following principles:

  • Progressive enhancement. JustFix services are used by tenants in a wide variety of devices and contexts that are difficult to predict. For example, many low-income individuals may need to use our services on computers with ancient browsers in housing court, or they may use older cell phones with outdated browsers.

    Due to this, we strive to build the platform in such a way that a baseline experience works on virtually any browser, and may optionally become progressively enhanced to harness the capabilities of the user's device and network connection.

  • Seamlessness. End-users should not experience layout instability or "jank" when using the site. For example, the initial page load should not result in different pieces of content popping in or out of view, potentially derailing a user's train of thought and causing anxiety.

  • Accessibility. The platform should be usable by anyone, regardless of any visual, motor, or cognitive impairments.

  • Stability. A suite of unit and integration help ensure that nothing accidentally breaks when we change things.

    Furthermore, wherever possible, we use tools like TypeScript and mypy to ensure that the site doesn't accidentally crash. These tools also allow us to more easily understand and refactor the codebase.

  • Resiliency. The platform is designed to work when third-party services may be down or unavailable. As a corollary, whenever possible, integration with third-party services should be optional, rather than required.

  • Security. The platform should be resistant to malicious attacks through the use of best practices such as Content Security Policy. Sensitive data should be protected by two-factor authentication, and other measures should be taken to ensure that users and their data are safe.

Architectural overview

The browser communicates with a Django server via HTTP GET/POST in the baseline state and GraphQL when progressively-enhanced. The Django server communicates with a JSX rendering service and a Postgres database.

The architecture consists of the following parts:

  • The user's browser needs to be capable of rendering HTML and submitting forms via standard HTTP GET and POST. This is the peanut from Aaron Gustafson's M&M metaphor for progressive enhancement.

    If CSS is available and has been delivered to the browser successfully, the page's content and core functionality is embellished with visual styling--the chocolate slathered on the peanut, as Gustafson would say.

    Finally, if JavaScript is available and has been delivered to the browser successfully, the experience is further enhanced with additional interactivity. Some fields are embellished with autocomplete functionality; forms are submitted via GraphQL, and page transitions make it easier for users to have a mental model of their experience. In Gustafson's metaphor, this is the sugary candy shell our confection is encased in.

  • The Django server responds to all requests from the user's browser.

  • The JSX rendering service, sometimes called "lambda", is responsible for rendering the user's intial page content (this mechanism is sometimes referred to as "server-side rendering", or SSR). This helps ensure that the user's experience is seamless, and also makes it possible for the site to work independently of JavaScript.

    At present, this service is spawned as a subprocess by the Django server, rather than being a separate server accessed over the network (though it may migrate to the latter someday).

  • The Postgres database stores all user data.

    Note that it is independent from an optional, secondary database containing open data about NYC (NYCDB).

Clone this wiki locally