# ilisien/the-dorsal architecture

> Architecture diagram of the GitHub repository ilisien/the-dorsal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilisien/the-dorsal
- Repository: https://github.com/ilisien/the-dorsal

## Overview

1. **What this repository is**
   - This is a **Django + Wagtail CMS** site for “The Dorsal” webpage.
   - The architecture is content-driven: most user-facing pages are rendered from Django templates, while editorial content is managed in Wagtail admin and stored in PostgreSQL.

2. **Top-level runtime and configuration**
   - The Django project lives in `dorsal/dorsal/` with the standard entrypoints: `settings.py`, `urls.py`, `wsgi.py`, and `asgi.py`.
   - `manage.py` is the local/admin command entrypoint.
   - `gen_txts.py` and the README’s `postgres_password.txt` workflow indicate the project expects local secret/config files generated at setup time rather than hardcoded credentials.

3. **Request routing and boundary between site and CMS**
   - The main URL dispatcher is `dorsal/dorsal/urls.py`.
   - App-specific routing is split into feature apps: `home`, `articles`, and `staff`, each with its own `urls.py`.
   - Wagtail admin is the editorial backend boundary; public pages are separate from the admin content management surface.

4. **Shared site shell and global pages**
   - The `globals` app provides shared presentation and generic page handling.
   - Its templates include `globals/base.html` and `globals/error.html`, which act as the common layout and error surface for the whole site.
   - This app is the likely home for site-wide navigation, base styling hooks, and reusable page chrome.

5. **Home section**
   - The `home` app handles the main landing experience and broader site sections.
   - Templates such as `home/index.html`, `home/generic.html`, and `home/section.html` suggest a mix of a homepage plus reusable section/page layouts.
   - `home/models.py`, `views.py`, `admin.py`, and migrations show it is not just static HTML; it participates in the Django model/admin stack.

6. **Articles subsystem**
   - The `articles` app is a core content subsystem for publishable article pages.
   - Its model evolution shows article metadata such as approval workflow, priority, section, author, title image, URL-encoded title, and a prologue/intro field.
   - Files like `edit_handlers.py`, `wagtail_hooks.py`, `signals.py`, and custom `image_formats.py` indicate deep Wagtail integration: custom admin editing behavior, editorial hooks, and image rendering behavior.

7. **Article rendering and workflow**
   - Public article rendering is handled by `articles/templates/articles/article.html` and `articles/views.py`.
   - The presence of approval-related migrations and signal handling suggests an editorial workflow where content may be gated or flagged before publication.
   - The app also defines a custom read-only admin panel template under `templates/wagtailadmin/panels/`, which implies some article fields are displayed without being directly editable.

8. **Staff subsystem**
   - The `staff` app manages staff profile content and presentation.
   - Models show profile data such as a `bio`/`short_bio` evolution, and `forms.py` suggests some profile input or editing interface beyond a plain model page.
   - Like articles, it has `signals.py` and `wagtail_hooks.py`, which means staff content is also integrated into Wagtail’s editorial experience and likely has custom admin behavior.

9. **Custom image/content media layer**
   - The `images` app extends the default Wagtail image system with project-specific models such as `InfoImage` and `InfoImageRendition`.
   - Migrations show additional metadata like image descriptions and file/rendition handling.
   - This layer is important because it separates site-specific image semantics from generic Django media handling.

10. **Static content and presentation assets**
   - The repository includes site copy in `static/markdown/` for pages like about, advertise, apply, contact, fonts, open-source, and physical-newspaper.
   - Styling is organized in SCSS under `static/scss/`, with separate bundles for home, articles, staff, navigation, fonts, colors, and shared initialization.
   - Fonts live under `static/fonts/`, so presentation is built from local assets rather than relying solely on a CDN.

11. **Persistence and development workflow**
   - Data is persisted through Django ORM migrations per app, backed by **PostgreSQL** per the setup guide.
   - Local development uses the standard Django/Wagtail loop: create env, install requirements, configure DB secrets, migrate, create a superuser, then run the server.
   - The main operational boundary is between public site views, Wagtail admin content management, and the relational database that stores all page/content state.

Main entry points: [`dorsal/dorsal/urls.py`](https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/urls.py) (URL router), [`dorsal/articles`](https://github.com/ilisien/the-dorsal/tree/master/dorsal/articles) (Articles), [`dorsal/home`](https://github.com/ilisien/the-dorsal/tree/master/dorsal/home) (Home), [`dorsal/static/scss`](https://github.com/ilisien/the-dorsal/tree/master/dorsal/static/scss) (SCSS styles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_manage["manage.py<br/>entrypoint<br/>[manage.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_urls["URL router<br/>routing<br/>[urls.py]"]
  node_wsgi["WSGI<br/>server entrypoint<br/>[wsgi.py]"]
  node_asgi["ASGI<br/>server entrypoint<br/>[asgi.py]"]
  node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_site["Public site"]
  node_globals["Globals<br/>shared site shell"]
  node_globals_base["Base layout<br/>template<br/>[base.html]"]
  node_globals_error["Error page<br/>template<br/>[error.html]"]
  node_home["Home<br/>page app"]
  node_home_views["Home views<br/>view layer<br/>[views.py]"]
  node_home_templates["Home templates"]
end

subgraph group_content["Content apps"]
  node_articles["Articles<br/>content app"]
  node_article_model["Article model<br/>content model<br/>[models.py]"]
  node_article_admin["Article admin<br/>Wagtail admin<br/>[edit_handlers.py]"]
  node_article_views["Article views<br/>view layer<br/>[views.py]"]
  node_staff["Staff<br/>content app"]
  node_staff_model["Staff model<br/>content model<br/>[models.py]"]
  node_staff_forms["Staff forms<br/>form layer<br/>[forms.py]"]
  node_images["Images<br/>media app"]
  node_images_model["Image models<br/>media model<br/>[models.py]"]
end

subgraph group_assets["Assets"]
  node_markdown["Markdown copy<br/>static content"]
  node_scss["SCSS styles<br/>stylesheets"]
end

node_manage -->|"loads"| node_settings
node_settings -->|"wires"| node_urls
node_urls -->|"serves"| node_globals
node_urls -->|"routes"| node_home
node_urls -->|"routes"| node_articles
node_urls -->|"routes"| node_staff
node_urls -->|"persists"| node_postgres
node_wsgi -->|"boots"| node_settings
node_asgi -->|"boots"| node_settings
node_globals -->|"renders"| node_globals_base
node_globals -->|"renders"| node_globals_error
node_home -->|"handles"| node_home_views
node_home -->|"renders"| node_home_templates
node_articles -->|"stores"| node_article_model
node_articles -->|"customizes"| node_article_admin
node_articles -->|"renders"| node_article_views
node_article_model -->|"persists"| node_postgres
node_staff -->|"stores"| node_staff_model
node_staff -->|"edits"| node_staff_forms
node_staff_model -->|"persists"| node_postgres
node_images -->|"stores"| node_images_model
node_images_model -->|"persists"| node_postgres
node_markdown -.->|"feeds"| node_home
node_scss -.->|"styles"| node_globals
node_scss -.->|"styles"| node_home
node_scss -.->|"styles"| node_articles
node_scss -.->|"styles"| node_staff

click node_manage "https://github.com/ilisien/the-dorsal/blob/master/dorsal/manage.py"
click node_settings "https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/settings.py"
click node_urls "https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/urls.py"
click node_wsgi "https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/wsgi.py"
click node_asgi "https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/asgi.py"
click node_globals "https://github.com/ilisien/the-dorsal/tree/master/dorsal/globals"
click node_globals_base "https://github.com/ilisien/the-dorsal/blob/master/dorsal/globals/templates/globals/base.html"
click node_globals_error "https://github.com/ilisien/the-dorsal/blob/master/dorsal/globals/templates/globals/error.html"
click node_home "https://github.com/ilisien/the-dorsal/tree/master/dorsal/home"
click node_home_views "https://github.com/ilisien/the-dorsal/blob/master/dorsal/home/views.py"
click node_home_templates "https://github.com/ilisien/the-dorsal/tree/master/dorsal/home/templates/home"
click node_articles "https://github.com/ilisien/the-dorsal/tree/master/dorsal/articles"
click node_article_model "https://github.com/ilisien/the-dorsal/blob/master/dorsal/articles/models.py"
click node_article_admin "https://github.com/ilisien/the-dorsal/blob/master/dorsal/articles/edit_handlers.py"
click node_article_views "https://github.com/ilisien/the-dorsal/blob/master/dorsal/articles/views.py"
click node_staff "https://github.com/ilisien/the-dorsal/tree/master/dorsal/staff"
click node_staff_model "https://github.com/ilisien/the-dorsal/blob/master/dorsal/staff/models.py"
click node_staff_forms "https://github.com/ilisien/the-dorsal/blob/master/dorsal/staff/forms.py"
click node_images "https://github.com/ilisien/the-dorsal/tree/master/dorsal/images"
click node_images_model "https://github.com/ilisien/the-dorsal/blob/master/dorsal/images/models.py"
click node_markdown "https://github.com/ilisien/the-dorsal/tree/master/dorsal/static/markdown"
click node_scss "https://github.com/ilisien/the-dorsal/tree/master/dorsal/static/scss"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manage,node_settings,node_urls,node_wsgi,node_asgi,node_postgres toneBlue
class node_globals,node_globals_base,node_globals_error,node_home,node_home_views,node_home_templates toneAmber
class node_articles,node_article_model,node_article_admin,node_article_views,node_staff,node_staff_model,node_staff_forms,node_images,node_images_model toneMint
class node_markdown,node_scss toneRose
```

## Components

### Platform

Django/Wagtail runtime, routing, and persistence boundary

- [manage.py](https://github.com/ilisien/the-dorsal/blob/master/dorsal/manage.py): entrypoint · Local Django command entrypoint · `dorsal/manage.py`
- [Settings](https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/settings.py): config · Project configuration and installed apps · `dorsal/dorsal/settings.py`
- [URL router](https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/urls.py): routing · Root request dispatcher for public site and admin · `dorsal/dorsal/urls.py`
- [WSGI](https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/wsgi.py): server entrypoint · Production synchronous server entrypoint · `dorsal/dorsal/wsgi.py`
- [ASGI](https://github.com/ilisien/the-dorsal/blob/master/dorsal/dorsal/asgi.py): server entrypoint · Async server entrypoint · `dorsal/dorsal/asgi.py`
- **PostgreSQL**: database · Relational store for content and site state

### Public site

Shared shell and public-facing page system

- [Globals](https://github.com/ilisien/the-dorsal/tree/master/dorsal/globals): shared site shell · Common layout, error pages, and reusable chrome · `dorsal/globals`
- [Base layout](https://github.com/ilisien/the-dorsal/blob/master/dorsal/globals/templates/globals/base.html): template · Site-wide page shell · `dorsal/globals/templates/globals/base.html`
- [Error page](https://github.com/ilisien/the-dorsal/blob/master/dorsal/globals/templates/globals/error.html): template · Shared error surface · `dorsal/globals/templates/globals/error.html`
- [Home](https://github.com/ilisien/the-dorsal/tree/master/dorsal/home): page app · Landing pages and generic section rendering · `dorsal/home`
- [Home views](https://github.com/ilisien/the-dorsal/blob/master/dorsal/home/views.py): view layer · Homepage and section/page views · `dorsal/home/views.py`
- [Home templates](https://github.com/ilisien/the-dorsal/tree/master/dorsal/home/templates/home): templates · Homepage, generic, and section layouts · `dorsal/home/templates/home`

### Content apps

Editorial subsystems managed through Wagtail and Django models

- [Articles](https://github.com/ilisien/the-dorsal/tree/master/dorsal/articles): content app · Editorial article publishing system · `dorsal/articles`
- [Article model](https://github.com/ilisien/the-dorsal/blob/master/dorsal/articles/models.py): content model · Article metadata and workflow fields · `dorsal/articles/models.py`
- [Article admin](https://github.com/ilisien/the-dorsal/blob/master/dorsal/articles/edit_handlers.py): Wagtail admin · Custom editing behavior and panels · `dorsal/articles/edit_handlers.py`
- [Article views](https://github.com/ilisien/the-dorsal/blob/master/dorsal/articles/views.py): view layer · Public article rendering · `dorsal/articles/views.py`
- [Staff](https://github.com/ilisien/the-dorsal/tree/master/dorsal/staff): content app · Staff profile content and presentation · `dorsal/staff`
- [Staff model](https://github.com/ilisien/the-dorsal/blob/master/dorsal/staff/models.py): content model · Profile data and bios · `dorsal/staff/models.py`
- [Staff forms](https://github.com/ilisien/the-dorsal/blob/master/dorsal/staff/forms.py): form layer · Profile editing/input support · `dorsal/staff/forms.py`
- [Images](https://github.com/ilisien/the-dorsal/tree/master/dorsal/images): media app · Project-specific image and rendition layer · `dorsal/images`
- [Image models](https://github.com/ilisien/the-dorsal/blob/master/dorsal/images/models.py): media model · Custom image and rendition records · `dorsal/images/models.py`

### Assets

Static presentation resources and source content

- [Markdown copy](https://github.com/ilisien/the-dorsal/tree/master/dorsal/static/markdown): static content · Site copy for mostly static pages · `dorsal/static/markdown`
- [SCSS styles](https://github.com/ilisien/the-dorsal/tree/master/dorsal/static/scss): stylesheets · Site styling bundles and shared variables · `dorsal/static/scss`

## Connections

- manage.py → Settings: loads · Command entrypoint uses project configuration
- Settings → URL router: wires · Settings enable root routing and apps
- URL router → Globals: serves · Routes shared site chrome and errors
- URL router → Home: routes · Dispatches home section URLs
- URL router → Articles: routes · Dispatches article URLs
- URL router → Staff: routes · Dispatches staff URLs
- URL router → PostgreSQL: persists · Site data ultimately stored in relational database
- WSGI → Settings: boots · WSGI imports project settings
- ASGI → Settings: boots · ASGI imports project settings
- Globals → Base layout: renders · Shared layout template
- Globals → Error page: renders · Shared error template
- Home → Home views: handles · Home app view logic
- Home → Home templates: renders · Home templates define public pages
- Articles → Article model: stores · Article records and editorial fields
- Articles → Article admin: customizes · Wagtail editing experience
- Articles → Article views: renders · Public article pages
- Article model → PostgreSQL: persists · Article content stored in database
- Staff → Staff model: stores · Staff profile records
- Staff → Staff forms: edits · Profile input and admin-side forms
- Staff model → PostgreSQL: persists · Staff content stored in database
- Images → Image models: stores · Custom image and rendition records
- Image models → PostgreSQL: persists · Media metadata stored in database
- Markdown copy → Home: feeds · Static copy supports site pages
- SCSS styles → Globals: styles · Shared presentation assets
- SCSS styles → Home: styles · Section-specific styling
- SCSS styles → Articles: styles · Article styling bundle
- SCSS styles → Staff: styles · Staff styling bundle
