How ilisien/the-dorsal works
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: urls.py URL router · articles Articles · home Home · scss SCSS styles
Components 23
Platform
Django/Wagtail runtime, routing, and persistence boundary
- manage.py · Local Django command entrypoint
dorsal/manage.py - Settings · Project configuration and installed apps
dorsal/dorsal/settings.py - URL router · Root request dispatcher for public site and admin
dorsal/dorsal/urls.py - WSGI · Production synchronous server entrypoint
dorsal/dorsal/wsgi.py - ASGI · Async server entrypoint
dorsal/dorsal/asgi.py - PostgreSQL · Relational store for content and site state
Public site
Shared shell and public-facing page system
- Globals · Common layout, error pages, and reusable chrome
dorsal/globals - Base layout · Site-wide page shell
dorsal/globals/templates/globals/base.html - Error page · Shared error surface
dorsal/globals/templates/globals/error.html - Home · Landing pages and generic section rendering
dorsal/home - Home views · Homepage and section/page views
dorsal/home/views.py - Home templates · Homepage, generic, and section layouts
dorsal/home/templates/home
Content apps
Editorial subsystems managed through Wagtail and Django models
- Articles · Editorial article publishing system
dorsal/articles - Article model · Article metadata and workflow fields
dorsal/articles/models.py - Article admin · Custom editing behavior and panels
dorsal/articles/edit_handlers.py - Article views · Public article rendering
dorsal/articles/views.py - Staff · Staff profile content and presentation
dorsal/staff - Staff model · Profile data and bios
dorsal/staff/models.py - Staff forms · Profile editing/input support
dorsal/staff/forms.py - Images · Project-specific image and rendition layer
dorsal/images - Image models · Custom image and rendition records
dorsal/images/models.py
Assets
Static presentation resources and source content
- Markdown copy · Site copy for mostly static pages
dorsal/static/markdown - SCSS styles · Site styling bundles and shared variables
dorsal/static/scss
Connections 27
- 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