eitchtee/wygiwyh

<explanation>

Below is a step‑by‑step guide to drawing a comprehensive system‑architecture diagram for WYGIWYH, tailored to its Django‑based monolith with a separate Webpack‑driven front end and background workers.

1. Identify the project type and purpose

• Full‑stack single‑code‑base web application

• Opinionated finance tracker with multi‑currency support, DCA tracker, rules engine, and API.

• Backend: Django (with DRF, HTMX, Hyperscript), Procrastinate for async tasks

• Frontend: Webpack bundle (Bootstrap, Tailwind, Alpine.js)

2. Analyze the file structure

• Top level:

– app/ (Django project and ~15 Django “apps” like accounts, transactions, currencies, import_app, export_app, etc.)

– frontend/ (Webpack config, src application scripts, styles)

– docker‑compose.dev.yml & prod (containers for Django web, Procrastinate worker, Supervisord, Webpack builder)

– requirements.txt (Python dependencies)

• Key configs: app/WYGIWYH/settings.py, docker/*, frontend/webpack/*.js

• Background tasks: app/apps/**/tasks.py, app/apps/rules/signals.py

• API layer: app/apps/api (DRF serializers, views, URLs)

3. Examine the README for additional insights

• Built with Django, HTMX, Procrastinate, DRF, Webpack, PostgreSQL

• Dockerized for prod/dev, environment variables for DB, secrets, feature flags

• Web UI + Automation‑ready API + scheduled background jobs (exchange rate fetcher, imports/exports)

4. Main components and interactions

a. Frontend (Browser & Static assets)

– Browser UI: HTML templates (Django + HTMX snippets) + JavaScript (webpack‑bundled scripts: htmx, hyperscript, jQuery, datepicker, etc.) + CSS (Bootstrap, Tailwind)

– Sends HTTP/HTMX requests to Backend

b. Django Web Server

– WSGI/ASGI app (app/WYGIWYH/wsgi.py & asgi.py)

– URL router → Django apps (views, DRF APIView)

– Templates → dynamic HTML + HTMX fragments

– Orchestrates business logic, form processing, rules engine

– Enqueues background jobs (via Procrastinate client)

c. PostgreSQL Database

– Stores users, accounts, transactions, currencies, DCA strategies, rules, import/export profiles, translations, etc.

– Django ORM / SQL queries

d. Background Worker (Procrastinate)

– Listens for enqueued jobs: exchange rate fetcher, import/app tasks, export tasks, recurring transaction generation, cleanup soft‑deleted transactions

– Runs scheduled jobs (cron‑like)

e. External Services

– Exchange rate providers (in app/apps/currencies/exchange_rates/providers.py)

– Translation service for localization (HerokuTranslate or similar)

– Optional integrations via API

5. Architectural patterns & design principles

• Monolithic MVC pattern (Django apps as modules)

• Separation of concerns:

– “apps/api” provides REST endpoints for automation

– “apps/common” holds shared utils, middleware, custom fields

– Each domain feature (accounts, transactions, rules, DCA, insights) in its own app

• HTMX/hyperscript for progressive enhancement—partial views and in‑page interactions

• Asynchronous task queue (Procrastinate) for long‑running or scheduled jobs

• Containerized micro‑services approach: Web, Worker, Build, Supervisord

6. Diagramming guidelines

• Use distinct shapes & colors:

– Rectangle with rounded corners: Application components (Frontend bundle, Django Web)

– Cylinder: Database (PostgreSQL)

– Rectangle with dashed border: External services (Exchange Rate API)

– Rectangle with solid border (another color): Background Worker

• Label each component clearly (e.g., “Django Web (uWSGI/ASGI)”)

• Draw directional arrows:

– Browser → Django Web (HTTP/HTMX requests)

– Django Web → DB (SQL queries)

– Django Web → Worker (Task enqueue over broker)

– Worker → DB (read/write)

– Worker → External Provider (HTTP)

• Group related Django apps inside the Web component box (e.g., group “accounts, transactions, rules, import_app, export_app” under “Domain Logic”)

• Color‑code by layer:

– UI (blue),

– Backend/API (green),

– Data store (orange),

– Background jobs (purple),

– External (gray)

7. Tailor to this project

• Highlight “HTMX endpoints” alongside “Django Templates” for partial updates

• Show “DRF API” as a RESTful interface separate from HTMX routes

• Include the Procrastinate broker (e.g., Redis or built‑in Postgres broker) if used

• Depict the Docker‑and‑Supervisord arrangement if you wish to show deployment topology:

– Container: Django Web + Supervisord

– Container: Procrastinate Worker

– Container: Webpack dev server (in dev)

• Emphasize environment variables driving behavior (SECRET_KEY, SQL_*, ENABLE_SOFT_DELETE, DEMO)

8. Final checklist for your diagram

[ ] Components labeled (Browser, Frontend Assets, Django Web, DB, Worker, External APIs)

[ ] Arrows with protocols/queue types (HTTP, SQL, Task Queue)

[ ] Color coding or shapes to differentiate layers

[ ] Groupings for domain apps vs. shared/common code

[ ] Note key technologies next to each component (e.g., “Django + DRF + HTMX”)

By following this structure, your diagram will clearly communicate WYGIWYH’s architecture: a monolithic Django service with progressive enhancement (HTMX), a REST API, a containerized build & runtime environment, a relational data store, and a background task system for asynchronous workflows.