# mollahhamza/yum-ai architecture

> Architecture diagram of the GitHub repository mollahhamza/yum-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mollahhamza/yum-ai
- Repository: https://github.com/mollahhamza/yum-ai

## Overview

1. **Repo shape: two delivered runtimes, one main product path.**  
   The repository is split into a React frontend and a Django backend. In the current codebase, the live architecture is a single-page app talking to a Django REST API. The README also mentions future FastAPI/AI services, but those are not present in the tree yet, so they should be treated as planned, not current, components.

2. **Frontend boundary: Vite + React SPA.**  
   `FRONTEND/` is a client application built with Vite. The key runtime entry points are `src/main.jsx` and `src/App.jsx`, with feature screens under `src/pages/` such as Dashboard, Inventory, Billing, Forecasting, AIInsights, Login, Register, Reports, and Settings. This implies the UI is organized as route-based pages rather than a server-rendered app.

3. **Frontend API integration is centralized.**  
   `src/lib/api.js` is the obvious shared API client layer. That is the main boundary where the UI likely converts user actions into HTTP calls to the backend. Styling is split between page CSS, global CSS, and Tailwind/PostCSS config, so visual concerns are kept inside the frontend package.

4. **Backend boundary: Django project with REST endpoints.**  
   `BACKEND/backend_project/` contains the Django project configuration (`settings.py`, `urls.py`, `asgi.py`, `wsgi.py`). The backend exposes JSON APIs through Django URLs and views, with Django REST Framework-style serializers in each app. This is a classic API server, not a monolithic server-rendered Django site.

5. **Backend is decomposed by business domain.**  
   The backend is split into Django apps: `orders`, `inventory`, `users`, `dashboard`, and `api`. Each app follows the same pattern: `models.py`, `serializers.py`, `views.py`, `urls.py`, plus `admin.py`, `tests.py`, and migrations. That structure shows the system is organized by bounded domain, not by technical layer alone.

6. **Orders is the core transactional subsystem.**  
   The README and file layout indicate `orders` manages menu items, order creation, payment processing, and billing history. It also has a management command, `seed_demo_data.py`, which suggests demo/test data can be loaded into the order flow. This is the main write-heavy path in the system.

7. **Inventory is a separate operational subsystem.**  
   `inventory` handles stock items and stock-related operations such as listing, searching, filtering, low-stock reporting, and quantity updates. Its API surface is distinct from orders, which helps keep stock management independent from POS/payment logic. This app likely feeds both operational UI and dashboard summaries.

8. **Dashboard is a read-only aggregation layer.**  
   The `dashboard` app appears to expose summary statistics rather than owning primary business data. The README describes a `/dashboard/stats/` endpoint with totals, popular items, and recent orders. Architecturally, this is a read model built from the transactional apps, not a separate source of truth.

9. **Users is the identity/account boundary.**  
   The `users` app is present with its own models, serializers, views, and migrations, which implies user/account data is isolated from the operational domains. The README says authentication is not enforced yet, so the current repo likely has the structure for user management without full auth enforcement in production form.

10. **Data flow is REST over JSON, then ORM to relational storage.**  
    The typical path is: React page → `api.js` → Django URL/view → serializer → model → database → JSON response. The presence of `db.sqlite3` shows local development is currently backed by SQLite, while the README describes PostgreSQL/MySQL as the intended production database layer.

11. **Current API boundaries are domain-prefixed.**  
    The documented routes show separate namespaces such as `/api/orders/...`, `/inventory/...`, and `/dashboard/...`. That means the URL structure maps directly to business domains, which is useful for diagramming: the frontend talks to one backend, but the backend is internally segmented by domain routes.

12. **Admin, tests, and migrations are supporting infrastructure.**  
    Every app has `admin.py` for Django admin exposure, `tests.py` for app-level testing, and migrations for schema evolution. This indicates the backend is designed to be managed through Django’s standard operational tooling, not via ad hoc scripts.

13. **Planned AI/ML and deployment pieces are not yet part of the runtime graph.**  
    The README mentions Gemini/Ollama, forecasting libraries, Docker, and GitHub Actions, but no corresponding service directories exist in the tree. For an accurate architecture diagram, those should be shown as future external integrations or roadmap items, not as live components in the current repository.

14. **Best diagram framing for this repo.**  
    Draw the current system as: React SPA on the left, Django REST backend in the middle, relational database on the right. Inside the backend, split into Orders, Inventory, Dashboard, and Users domains, with shared Django project configuration above them and the Django admin/management command tooling alongside them.

Main entry points: [`FRONTEND/src/App.jsx`](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/App.jsx) (SPA shell), [`BACKEND/backend_project/settings.py`](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/backend_project/settings.py) (Project config), [`BACKEND/orders/views.py`](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/orders/views.py) (Orders), [`FRONTEND/src/lib/api.js`](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/lib/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>React app<br/>[App.jsx]"]
  node_frontend_main(("Entry<br/>[main.jsx]"))
  node_frontend_api["API client<br/>HTTP layer<br/>[api.js]"]
  node_frontend_dashboard["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_frontend_inventory["Inventory<br/>page<br/>[Inventory.jsx]"]
  node_frontend_billing["Billing<br/>page<br/>[Billing.jsx]"]
  node_frontend_ai["AI insights<br/>page<br/>[AIInsights.jsx]"]
  node_frontend_auth["Auth pages<br/>page cluster<br/>[Login.jsx]"]
  node_frontend_reports["Reports<br/>page<br/>[Reports.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_manage(("Manage<br/>Django CLI<br/>[manage.py]"))
  node_backend_settings["Project config<br/>Django project<br/>[settings.py]"]
  node_backend_orders["Orders<br/>domain app<br/>[views.py]"]
  node_backend_inventory["Inventory<br/>domain app<br/>[views.py]"]
  node_backend_dashboard["Dashboard API<br/>read model<br/>[views.py]"]
  node_backend_users["Users<br/>identity app<br/>[views.py]"]
  node_backend_api["Shared API<br/>support app<br/>[views.py]"]
  node_backend_db[("SQLite DB<br/>relational store<br/>[db.sqlite3]")]
  node_backend_seed["Seed data<br/>management command<br/>[seed_demo_data.py]"]
end

node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_app -->|"routes to"| node_frontend_dashboard
node_frontend_app -->|"routes to"| node_frontend_inventory
node_frontend_app -->|"routes to"| node_frontend_billing
node_frontend_app -->|"routes to"| node_frontend_ai
node_frontend_app -->|"routes to"| node_frontend_auth
node_frontend_app -->|"routes to"| node_frontend_reports
node_frontend_dashboard -->|"calls"| node_frontend_api
node_frontend_inventory -->|"calls"| node_frontend_api
node_frontend_billing -->|"calls"| node_frontend_api
node_frontend_ai -->|"calls"| node_frontend_api
node_backend_manage -->|"loads"| node_backend_settings
node_backend_settings -->|"includes"| node_backend_orders
node_backend_settings -->|"includes"| node_backend_inventory
node_backend_settings -->|"includes"| node_backend_dashboard
node_backend_settings -->|"includes"| node_backend_users
node_backend_settings -->|"includes"| node_backend_api
node_backend_orders -->|"persists"| node_backend_db
node_backend_inventory -->|"persists"| node_backend_db
node_backend_users -->|"persists"| node_backend_db
node_backend_dashboard -->|"reads from"| node_backend_orders
node_backend_dashboard -->|"reads from"| node_backend_inventory
node_backend_seed -.->|"seeds"| node_backend_orders

click node_frontend_app "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/App.jsx"
click node_frontend_main "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/main.jsx"
click node_frontend_api "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/lib/api.js"
click node_frontend_dashboard "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Dashboard.jsx"
click node_frontend_inventory "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Inventory.jsx"
click node_frontend_billing "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Billing.jsx"
click node_frontend_ai "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/AIInsights.jsx"
click node_frontend_auth "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Login.jsx"
click node_frontend_reports "https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Reports.jsx"
click node_backend_manage "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/manage.py"
click node_backend_settings "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/backend_project/settings.py"
click node_backend_orders "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/orders/views.py"
click node_backend_inventory "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/inventory/views.py"
click node_backend_dashboard "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/dashboard/views.py"
click node_backend_users "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/users/views.py"
click node_backend_api "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/api/views.py"
click node_backend_db "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/db.sqlite3"
click node_backend_seed "https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/orders/management/commands/seed_demo_data.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_main,node_frontend_api,node_frontend_dashboard,node_frontend_inventory,node_frontend_billing,node_frontend_ai,node_frontend_auth,node_frontend_reports toneBlue
class node_backend_manage,node_backend_settings,node_backend_orders,node_backend_inventory,node_backend_dashboard,node_backend_users,node_backend_api,node_backend_db,node_backend_seed toneAmber
```

## Components

### Frontend

Vite + React single-page application

- [SPA shell](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/App.jsx): React app · Top-level client shell and page composition · `FRONTEND/src/App.jsx`
- [Entry](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/main.jsx): Vite entry · Client bootstrap and mount point · `FRONTEND/src/main.jsx`
- [API client](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/lib/api.js): HTTP layer · Shared frontend backend-calling module · `FRONTEND/src/lib/api.js`
- [Dashboard](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Dashboard.jsx): page · Main summary and navigation surface · `FRONTEND/src/pages/Dashboard.jsx`
- [Inventory](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Inventory.jsx): page · Stock management screen · `FRONTEND/src/pages/Inventory.jsx`
- [Billing](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Billing.jsx): page · Order payment and billing UI · `FRONTEND/src/pages/Billing.jsx`
- [AI insights](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/AIInsights.jsx): page · Insights and forecast-oriented UI · `FRONTEND/src/pages/AIInsights.jsx`
- [Auth pages](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Login.jsx): page cluster · Login and registration screens · `FRONTEND/src/pages/Login.jsx`
- [Reports](https://github.com/mollahhamza/yum-ai/blob/main/FRONTEND/src/pages/Reports.jsx): page · Reporting and export views · `FRONTEND/src/pages/Reports.jsx`

### Backend

Django REST API and domain apps

- [Manage](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/manage.py): Django CLI · Project management entrypoint · `BACKEND/manage.py`
- [Project config](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/backend_project/settings.py): Django project · Settings, routing, ASGI, and WSGI configuration · `BACKEND/backend_project/settings.py`
- [Orders](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/orders/views.py): domain app · Order creation, menu items, payments, and billing history · `BACKEND/orders/views.py`
- [Inventory](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/inventory/views.py): domain app · Stock items, search, filtering, and updates · `BACKEND/inventory/views.py`
- [Dashboard API](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/dashboard/views.py): read model · Aggregated stats and recent activity endpoints · `BACKEND/dashboard/views.py`
- [Users](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/users/views.py): identity app · Account and user boundary · `BACKEND/users/views.py`
- [Shared API](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/api/views.py): support app · General backend API module · `BACKEND/api/views.py`
- [SQLite DB](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/db.sqlite3): relational store · Local development database backing Django ORM · `BACKEND/db.sqlite3`
- [Seed data](https://github.com/mollahhamza/yum-ai/blob/main/BACKEND/orders/management/commands/seed_demo_data.py): management command · Demo data loader for orders · `BACKEND/orders/management/commands/seed_demo_data.py`

## Connections

- Entry → SPA shell: mounts · Bootstraps the SPA shell
- SPA shell → Dashboard: routes to · Navigates to the dashboard page
- SPA shell → Inventory: routes to · Navigates to inventory management
- SPA shell → Billing: routes to · Navigates to billing flow
- SPA shell → AI insights: routes to · Navigates to insights and forecasting views
- SPA shell → Auth pages: routes to · Navigates to login and registration
- SPA shell → Reports: routes to · Navigates to reporting views
- Dashboard → API client: calls · Uses shared HTTP client for backend requests
- Inventory → API client: calls · Uses shared HTTP client for stock operations
- Billing → API client: calls · Uses shared HTTP client for order and payment actions
- AI insights → API client: calls · Uses shared HTTP client for analytics data
- Manage → Project config: loads · Starts the Django project runtime
- Project config → Orders: includes · Registers orders app routes and models
- Project config → Inventory: includes · Registers inventory app routes and models
- Project config → Dashboard API: includes · Registers dashboard app routes and models
- Project config → Users: includes · Registers users app routes and models
- Project config → Shared API: includes · Registers shared API app
- Orders → SQLite DB: persists · Stores transactional order data
- Inventory → SQLite DB: persists · Stores stock data
- Users → SQLite DB: persists · Stores user/account data
- Dashboard API → Orders: reads from · Aggregates order statistics
- Dashboard API → Inventory: reads from · Aggregates stock summaries
- Seed data → Orders: seeds · Loads demo order data