# h-iori/mealmatrix architecture

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

- Interactive diagram: https://gitdiagram.com/h-iori/mealmatrix
- Repository: https://github.com/h-iori/mealmatrix

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% Level 1: System Context
  %% =======================
  subgraph "C4-L1 System Context"
    U["User\n(Web Browser)"]:::person
    ADM["Admin User\n(Django Admin)"]:::person

    subgraph "MealMatrix (Monolithic Django Web App)"
      MM["MealMatrix\n(Django server-rendered app)"]:::service
    end

    DB[("SQLite Database\n(db.sqlite3)")]:::db
    OAI["External Diet/AI Provider\n(OpenAI API - optional)"]:::external
  end

  U -->|"HTTPS GET/POST (HTML+forms)"| MM
  MM -->|"HTML responses"| U
  ADM -->|"HTTPS (admin site)"| MM

  MM -->|"ORM read/write (users,plans,history)"| DB
  MM -->|"HTTPS JSON (prompt/completion)"| OAI

  %% =======================
  %% Level 2: Containers
  %% =======================
  subgraph "C4-L2 Containers / Runtime Boundaries"
    direction TB

    subgraph "Client"
      BROW["Browser UI\n(HTML/CSS/JS)\nBootstrap 5 + FontAwesome (CDN)"]:::frontend
    end

    subgraph "Django Runtime (Server)"
      direction TB
      ENTRY["manage.py\n(dev entrypoint)"]:::code
      WSGI["WSGI App\n(mealmatrix/wsgi.py)"]:::service
      ASGI["ASGI App\n(mealmatrix/asgi.py)"]:::service

      subgraph "Django Project: mealmatrix/"
        direction TB
        SETTINGS["Settings\n(mealmatrix/settings.py)"]:::code
        ROOTURLS["Root URLConf\n(mealmatrix/urls.py)"]:::code
      end

      subgraph "Django App: main_app/"
        direction TB
        APPPKG["App Package\n(main_app/)"]:::code
        APPURLS["App URLConf\n(main_app/urls.py)"]:::code
        VIEWS["Controllers / Views\n(main_app/views.py)"]:::code
        MODELS["Models / ORM Entities\n(main_app/models.py)"]:::code
        MIGR["Migrations\n(main_app/migrations/)"]:::artifact
        ADMINCFG["Admin Registration\n(main_app/admin.py)"]:::code
        TESTS["Tests\n(main_app/tests.py)"]:::artifact

        subgraph "Presentation"
          direction TB
          TMPL["Templates\n(main_app/templates/)"]:::ui
          STATIC["Static Source Assets\n(main_app/static/)\n(images,css,js)"]:::ui
        end
      end
    end

    subgraph "Data Store"
      SQLITE[("SQLite File\n(db.sqlite3)")]:::db
    end

    subgraph "Static Serving"
      direction TB
      COLLECTED["Collected Static\n(staticfiles/)\n(deployment artifact)"]:::artifact
    end
  end

  %% Container connections
  BROW -->|"HTTP requests"| WSGI
  BROW -->|"HTTP requests"| ASGI
  ENTRY -->|"runserver / management"| WSGI

  SETTINGS -->|"configures"| WSGI
  SETTINGS -->|"configures"| ASGI
  ROOTURLS -->|"include() routes"| APPURLS
  APPURLS -->|"dispatch to"| VIEWS
  VIEWS -->|"render(context)"| TMPL
  VIEWS -->|"serve static (dev)"| STATIC
  VIEWS -->|"ORM read/write"| MODELS
  MODELS -->|"migrate schema"| MIGR
  MODELS -->|"persist/query"| SQLITE
  ADMINCFG -->|"register models"| MODELS
  TESTS -->|"exercise"| VIEWS

  STATIC -->|"collectstatic"| COLLECTED
  TMPL -->|"HTML pages"| BROW

  %% External API call from views (optional)
  VIEWS -->|"diet plan generation (optional)"| OAI

  %% =======================
  %% Level 3: Key Flows (as a vertical mini-map)
  %% =======================
  subgraph "Key Request Flows (Server-rendered)"
    direction TB
    F1["Auth Flow\nsignup/login/logout\n(Django Auth sessions/cookies)"]:::flow
    F2["Generate Diet Plan\nvalidate -> compute/call AI -> save -> render"]:::flow
    F3["View History\nquery user plans -> render overview"]:::flow
  end

  BROW -->|"POST credentials"| F1 -->|"create session"| VIEWS
  BROW -->|"POST metrics+goal"| F2 -->|"orchestrate"| VIEWS
  BROW -->|"GET overview"| F3 -->|"query"| VIEWS

  %% =======================
  %% Click Events (from mapping)
  %% =======================
  click ENTRY "https://github.com/h-iori/mealmatrix/blob/main/manage.py"
  click SETTINGS "https://github.com/h-iori/mealmatrix/blob/main/mealmatrix/settings.py"
  click WSGI "https://github.com/h-iori/mealmatrix/blob/main/mealmatrix/wsgi.py"
  click ASGI "https://github.com/h-iori/mealmatrix/blob/main/mealmatrix/asgi.py"
  click ROOTURLS "https://github.com/h-iori/mealmatrix/blob/main/mealmatrix/urls.py"

  click APPPKG "https://github.com/h-iori/mealmatrix/tree/main/main_app/"
  click APPURLS "https://github.com/h-iori/mealmatrix/blob/main/main_app/urls.py"
  click VIEWS "https://github.com/h-iori/mealmatrix/blob/main/main_app/views.py"
  click MODELS "https://github.com/h-iori/mealmatrix/blob/main/main_app/models.py"
  click SQLITE "https://github.com/h-iori/mealmatrix/blob/main/db.sqlite3"
  click MIGR "https://github.com/h-iori/mealmatrix/tree/main/main_app/migrations/"
  click ADMINCFG "https://github.com/h-iori/mealmatrix/blob/main/main_app/admin.py"
  click TMPL "https://github.com/h-iori/mealmatrix/tree/main/main_app/templates/"
  click STATIC "https://github.com/h-iori/mealmatrix/tree/main/main_app/static/"
  click COLLECTED "https://github.com/h-iori/mealmatrix/tree/main/staticfiles/"
  click TESTS "https://github.com/h-iori/mealmatrix/blob/main/main_app/tests.py"

  %% =======================
  %% Styles
  %% =======================
  classDef person fill:#FFE6A7,stroke:#8A6D3B,stroke-width:1px,color:#2B2B2B;
  classDef service fill:#CFE8FF,stroke:#1F6FEB,stroke-width:1.2px,color:#0B1F3A;
  classDef db fill:#D7F7E7,stroke:#1E8E5A,stroke-width:1.2px,color:#0B3A23;
  classDef external fill:#FAD1D1,stroke:#C81E1E,stroke-width:1.2px,color:#3A0B0B;
  classDef code fill:#DFF6DD,stroke:#2E7D32,stroke-width:1px,color:#0E2A10;
  classDef ui fill:#E8E8E8,stroke:#616161,stroke-width:1px,color:#1F1F1F;
  classDef artifact fill:#EFE7FF,stroke:#6F42C1,stroke-width:1px,color:#1E1033;
  classDef frontend fill:#D6F0FF,stroke:#0B74B8,stroke-width:1px,color:#07263A;
  classDef flow fill:#FFF2CC,stroke:#B7791F,stroke-width:1px,color:#3A2507;
```
