Architecture Overview

Purpose

This is the primary navigation document for the repository. Use it to identify boundaries, entry points, and operational dependencies before making changes.

System boundaries

ByteRaccoon is a Wagtail (Django) backend with a Tailwind v4 + Preline frontend build.

  • Backend: page models, routing, rendering, tests.
  • Frontend: CSS/JS build pipeline only.
  • Data services (deployment target): PostgreSQL, Redis, S3 media.
  • Compute target: AWS AppRunner.

Module map

flowchart LR FE[Frontend build] --> STATIC[backend/static/build] STATIC --> BACKEND[Django and Wagtail] BACKEND --> BLOG[blog app] BACKEND --> SEARCH[search app] BACKEND --> SETTINGS[site_settings app] BACKEND --> TPL[Templates]

Runtime request flow

flowchart LR Browser --> URLS[backend/backend/urls.py] URLS -->|/search/| SEARCH[search.views.search] URLS -->|/blog/tag/<slug>/| TAG[blog.views.tag_detail] URLS -->|all other paths| WAGTAIL[Wagtail page routing] SEARCH --> WQ[Page.objects.live().search] TAG --> BP[BlogPage query] WAGTAIL --> TPL[Template rendering]

Code entry points

Area Path Notes
Django entry backend/manage.py Local management commands.
URL routing backend/backend/urls.py Search/tag routes plus Wagtail fallback.
Base settings backend/backend/settings/base.py Shared Django and Wagtail configuration.
Blog models backend/blog/models.py BlogIndexPage, BlogPage, StreamField blocks.
Blog views backend/blog/views.py Tag detail listing.
Search view backend/search/views.py Query and pagination behavior.
Site settings backend/site_settings/models.py Footer and navigation settings models.
Base layout backend/backend/templates/base.html Site shell, search form, footer include.
Frontend styles frontend/src/main.css Tailwind source.
Frontend scripts frontend/src/main.js Preline and frontend behavior.

UI and navigation constraints

  • RECENT_ARTICLES is the primary site navigation intent.
  • Do not add header navigation link rendering; keep navigation single-source.
  • Use shared br-* typography classes instead of ad hoc Tailwind font-size utilities.

Documentation index

  • Root project and docs index: README.md
  • Deployed docs wiki home: docs/README.md
  • Features index: docs/Features/README.md
  • Search: docs/Features/Application/Search.md
  • Smoke tests: docs/Features/Operations/SmokeTests.md
  • Developer tooling: docs/Features/Operations/DeveloperTooling.md
  • Security and static analysis: docs/Features/Operations/SecurityStaticAnalysis.md
  • Layout background: docs/Features/Frontend/LayoutBackground.md
  • Color palette: docs/Features/Frontend/ColorPalette.md
  • Blog template HTML validity: docs/Features/Frontend/BlogTemplateHtml.md
  • Footer content settings: docs/Features/Application/Footer.md
  • Newsletter and paywall strategy: docs/Features/Strategy/NewsletterPaywallStrategy.md
  • Codex contributor workflow: docs/Workflow/AI-Codex.md
  • MkDocs workflow: docs/Workflow/MkDocsWorkflow.md

Change checklist

  • Identify which boundary you are changing.
  • Update tests first for behavior changes.
  • Run relevant verification commands.
  • Update the affected feature document.
  • Keep this overview in sync when entry points or boundaries change.