How h-iori/mealmatrix works
Project type + purpose (what you’re diagramming)
This is a monolithic Django web application (“MealMatrix”) that server-renders HTML (Django templates) and generates personalized diet plans for authenticated users, storing user/diet history in SQLite (db.sqlite3). It likely also calls an external AI service (README instructs pip install openai), so treat “Diet Plan Generation” as either an internal rules engine or an external dependency (or both).
Key architectural cues from the tree:
• mealmatrix/ = Django project (settings, root URLs, WSGI/ASGI entrypoints)
• main_app/ = primary Django app (models, views, urls, templates, static)
• db.sqlite3 = local relational datastore
• staticfiles/ = collected static assets (not source-of-truth; deployment artifact)
• main_app/templates/*.html = server-side pages: login/signup/dashboard/diet overview/response
How to partition the system into “as many components as possible” (but still accurate)
Include:
• User (Web Browser / Mobile Browser)
• MealMatrix Web App (Django)
• SQLite DB
• (Optional) Admin User using Django Admin (same app, different interface)
• Browser ⇄ Django: HTTPS requests/responses (HTML pages + form posts)
• Django ⇄ SQLite: ORM queries (users, diet plans, history)
• Django ⇄ External API: diet plan generation request/response (JSON over HTTPS)
Even though it’s a monolith, break it into runtime containers:
• Client: Browser rendering HTML/CSS/Bootstrap/FontAwesome
• Web Server / Django Runtime:
• mealmatrix/wsgi.py (prod) and/or mealmatrix/asgi.py (async-capable)
• URL routing: mealmatrix/urls.py → main_app/urls.py
• Views: main_app/views.py
• Templates: main_app/templates/*
• Static source: main_app/static/*
• Database: SQLite file (db.sqlite3)
• Static file serving:
• In dev: Django staticfiles
• In prod: typically Nginx/Whitenoise; your repo shows staticfiles/ so note “collected static” artifact
• External Service (if applicable): OpenAI
Make the boundaries explicit:
• “Django Project (mealmatrix)” vs “Django App (main_app)”
• “Runtime vs Build/collectstatic artifact” (staticfiles)
This is where the file tree gives you clean component boundaries:
Routing Layer
• mealmatrix/urls.py (root router)
• main_app/urls.py (feature routes)
Application/Controller Layer
• main_app/views.py:
• Auth flows (signup/login/logout) – likely uses Django auth
• Form handling for diet plan input
• “Generate plan” orchestration (validate → compute/call API → persist → render response)
• History retrieval for dashboard/overview
Domain/Data Layer
• main_app/models.py:
• User Profile (or uses Django User)
• DietPlan / DietHistory (date created, goals, metrics, output text)
• main_app/migrations/0001_initial.py as schema provenance
Admin/Backoffice
• main_app/admin.py to manage models via Django Admin
• staticfiles/admin/* = admin static assets (deployment artifact)
Configuration/Bootstrap
• mealmatrix/settings.py (INSTALLED_APPS, middleware, templates config, static config, DB config, auth settings)
• manage.py (entrypoint)
Relationships:
• urls.py → views.py
• views.py → models.py (ORM)
• views.py → templates (render)
• views.py → external API client (if used) → response → persisted to DB
• admin → models
Browser requests /signup → Django returns signup.html
2. Browser posts signup form → view validates → creates user (Django auth) → redirects to login/dashboard
View
• validates input
• computes BMR/TDEE/macros OR calls external OpenAI prompt
• constructs diet plan result
• saves DietPlan/DietHistory row in SQLite
Server renders response.html
5. Optional: user later visits dietoverview.html → view queries history → renders list/details
Flow 3: View History
• Dashboard/overview route → ORM query (filter by authenticated user) → render dietoverview.html
From README/tree:
• Django (routing, views, templates, ORM, auth, admin)
• SQLite (db.sqlite3)
• Bootstrap 5 (UI responsiveness; include as “CSS framework” in client)
Both entrypoints:
• wsgi.py (sync server e.g., Gunicorn)
• asgi.py (async server e.g., Uvicorn/Daphne) — even if not used today, it’s part of deploy surface
System Context (1 page)
2. Container/Deployment (1 page): Browser, Django (WSGI/ASGI), SQLite, external API, static serving
This set is detailed, faithful to the repo structure, and “separates into as many components as possible” without hallucinating services that don’t exist.