# shelji/mobi-pills architecture

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

- Interactive diagram: https://gitdiagram.com/shelji/mobi-pills
- Repository: https://github.com/shelji/mobi-pills

## Overview

1. **High-level shape**
   - This is a single Django monolith for a mobile shop sales/billing system.
   - The backend and UI live in the same codebase: Django handles routing, rendering, authentication, models, and APIs; HTML templates provide the user interface.

2. **Project entrypoints and runtime**
   - `manage.py` is the standard Django management entrypoint.
   - `mobi_pills/wsgi.py` and `mobi_pills/asgi.py` expose the app for classic WSGI and async-capable deployment.
   - `main.py` is an additional top-level launcher/helper, likely used for local startup or platform-specific execution.
   - `.cpanel.yml` indicates deployment on a cPanel-style host.

3. **Core domain boundary: `shop` app**
   - Almost all business logic sits inside the `shop` Django app.
   - This app contains models, views, API endpoints, serializers, admin registration, context processors, URL routing, and custom management commands.
   - That makes `shop` the main architectural boundary for products, customers, billing, suppliers, sales, and stock-related workflows.

4. **Data model and persistence**
   - Schema evolution is captured in Django migrations under `shop/migrations`.
   - The migration names show the main domain entities and refinements: `Product`, `Customer`, `Supplier`, `Address`, `Expense`, product IMEI support, quick products, and product image handling.
   - The app is clearly relational and database-backed, with Django ORM as the persistence layer.

5. **Billing and sales flow**
   - The README describes the central workflow: create bills with multiple products, auto-calculate totals/tax/discount, generate invoice numbers, and produce printable/downloadable invoices.
   - The template set includes `billing.html`, `invoice_detail.html`, and `sales.html`, which suggests a mixed workflow of form-driven bill creation and transaction review.
   - Sales data is likely persisted as order/invoice records with line items tied back to products.

6. **Product and inventory management**
   - `products.html`, `categories.html`, `suppliers.html`, and `customers.html` indicate CRUD-oriented screens for core inventory and relationship data.
   - The README emphasizes stock tracking, low-stock alerts, image upload, filtering/search, and optional IMEI tracking for phones.
   - The custom management command `convert_product_images.py` suggests the app also handles image migration/normalization for product assets.

7. **API layer versus server-rendered views**
   - The repository contains both `shop/views.py` and `shop/api_views.py`, plus `shop/serializers.py`.
   - That implies two access patterns over the same domain models:
     - server-rendered HTML pages for the main UI,
     - JSON APIs for async actions such as billing updates, search/filtering, or dashboard refreshes.
   - This is reinforced by the README’s request for AJAX/fetch-based interactions.

8. **Presentation layer**
   - UI pages are rendered from `templates/base.html` and `templates/shop/*`.
   - The main pages include `dashboard.html`, `productive_dashboard.html`, `home.html`, and the business screens for products, customers, suppliers, sales, and billing.
   - There is no separate SPA frontend; the app appears to be a Django template-based UI, likely enhanced with JavaScript for responsive interactions.

9. **Dashboard and reporting**
   - The dashboard is a first-class screen, with templates for both the main dashboard and a “productive” dashboard variant.
   - The README calls for daily/weekly/monthly sales totals, recent transactions, low-stock alerts, and quick actions.
   - `seed_dashboard.py` suggests the dashboard may be prepopulated with sample metrics or example data for demos/testing.

10. **Authentication and access control**
   - The README specifies Django built-in authentication with role separation between admin/staff.
   - In architectural terms, this means Django auth is the gatekeeper, while the `shop` views likely enforce role-based access around management versus billing-only tasks.
   - The admin interface is also exposed via `shop/admin.py`, which is the secondary management surface for internal users.

11. **Supporting infrastructure and automation**
   - `create_sample_data.py` and `seed_dashboard.py` are developer/data seeding utilities, likely used to bootstrap realistic demo content.
   - `shop/tests.py` shows at least a minimal test boundary for business logic or view behavior.
   - `pyproject.toml` and `uv.lock` indicate dependency management via modern Python packaging tooling.

12. **Deployment and file handling**
   - The README mentions environment-variable-based configuration, static/media handling, and `django-dbbackup`.
   - That means the app expects externalized settings for secret keys, database, and media paths, plus file storage for product images and invoice-related assets.
   - The backup workflow is part of operations rather than core business logic, but it matters because product images and DB snapshots are integral to recovery.

13. **What to draw in an architecture diagram**
   - Show a browser/mobile client hitting Django routes in two ways: template-rendered pages and JSON API endpoints.
   - Put the `shop` app in the center, connected to the database through Django ORM and migrations.
   - Include the admin interface as a separate internal management path.
   - Add supporting boxes for sample-data scripts, custom management commands, and deployment entrypoints (WSGI/ASGI/cPanel).

Main entry points: [`shop/models.py`](https://github.com/shelji/mobi-pills/blob/main/shop/models.py) (Models), [`mobi_pills/settings.py`](https://github.com/shelji/mobi-pills/blob/main/mobi_pills/settings.py) (Settings), [`shop/views.py`](https://github.com/shelji/mobi-pills/blob/main/shop/views.py) (Views), [`mobi_pills/urls.py`](https://github.com/shelji/mobi-pills/blob/main/mobi_pills/urls.py) (Project URLs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_entry["Entrypoints"]
  node_manage_py["manage.py<br/>Django entrypoint<br/>[manage.py]"]
  node_main_py["main.py<br/>local launcher<br/>[main.py]"]
  node_wsgi_asgi["WSGI/ASGI<br/>deploy adapters<br/>[wsgi.py]"]
end

subgraph group_g_core["Django core"]
  node_settings["Settings<br/>project config<br/>[settings.py]"]
  node_project_urls["Project URLs<br/>route map<br/>[urls.py]"]
end

subgraph group_g_shop["Shop app"]
  node_shop_urls["Shop URLs<br/>app routes<br/>[urls.py]"]
  node_models[("Models<br/>ORM schema<br/>[models.py]")]
  node_views["Views<br/>[views.py]"]
  node_api_views["API views<br/>JSON endpoints<br/>[api_views.py]"]
  node_serializers["Serializers<br/>API schema<br/>[serializers.py]"]
  node_admin["Admin<br/>management UI<br/>[admin.py]"]
  node_context_processors["Context"]
  node_migrations["Migrations<br/>schema history<br/>[0001_initial.py]"]
end

subgraph group_g_ui["Presentation"]
  node_templates["Templates<br/>UI pages<br/>[base.html]"]
end

subgraph group_g_ops["Support"]
  node_seed_scripts["Seed data<br/>bootstrap scripts"]
  node_convert_images["Image convert<br/>management command"]
end

node_users(("Users<br/>actor"))
node_database[("Database<br/>persistent store")]

node_users -->|"browse app"| node_project_urls
node_manage_py -->|"loads"| node_settings
node_manage_py -->|"runs"| node_project_urls
node_main_py -->|"launches"| node_wsgi_asgi
node_wsgi_asgi -->|"serves"| node_project_urls
node_project_urls -->|"delegates"| node_shop_urls
node_shop_urls -->|"maps"| node_views
node_shop_urls -->|"maps"| node_api_views
node_views -->|"reads/writes"| node_models
node_api_views -->|"uses"| node_serializers
node_api_views -->|"reads/writes"| node_models
node_views -->|"renders"| node_templates
node_views -->|"injects"| node_context_processors
node_templates -->|"displays"| node_models
node_models -->|"evolves via"| node_migrations
node_models -->|"persists to"| node_database
node_admin -->|"manages"| node_models
node_seed_scripts -->|"seeds"| node_database
node_convert_images -->|"updates assets"| node_models
node_settings -->|"configures"| node_database
node_settings -->|"configures"| node_templates
node_settings -->|"enables"| node_admin

click node_manage_py "https://github.com/shelji/mobi-pills/blob/main/manage.py"
click node_main_py "https://github.com/shelji/mobi-pills/blob/main/main.py"
click node_wsgi_asgi "https://github.com/shelji/mobi-pills/blob/main/mobi_pills/wsgi.py"
click node_settings "https://github.com/shelji/mobi-pills/blob/main/mobi_pills/settings.py"
click node_project_urls "https://github.com/shelji/mobi-pills/blob/main/mobi_pills/urls.py"
click node_shop_urls "https://github.com/shelji/mobi-pills/blob/main/shop/urls.py"
click node_models "https://github.com/shelji/mobi-pills/blob/main/shop/models.py"
click node_views "https://github.com/shelji/mobi-pills/blob/main/shop/views.py"
click node_api_views "https://github.com/shelji/mobi-pills/blob/main/shop/api_views.py"
click node_serializers "https://github.com/shelji/mobi-pills/blob/main/shop/serializers.py"
click node_admin "https://github.com/shelji/mobi-pills/blob/main/shop/admin.py"
click node_context_processors "https://github.com/shelji/mobi-pills/blob/main/shop/context_processors.py"
click node_migrations "https://github.com/shelji/mobi-pills/blob/main/shop/migrations/0001_initial.py"
click node_templates "https://github.com/shelji/mobi-pills/blob/main/templates/base.html"
click node_seed_scripts "https://github.com/shelji/mobi-pills/blob/main/create_sample_data.py"
click node_convert_images "https://github.com/shelji/mobi-pills/blob/main/shop/management/commands/convert_product_images.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_manage_py,node_main_py,node_wsgi_asgi toneBlue
class node_settings,node_project_urls toneAmber
class node_shop_urls,node_models,node_views,node_api_views,node_serializers,node_admin,node_context_processors,node_migrations toneMint
class node_templates toneRose
class node_seed_scripts,node_convert_images toneIndigo
class node_users,node_database toneNeutral
```

## Components

### Entrypoints

Process launchers and deployment hooks.

- [manage.py](https://github.com/shelji/mobi-pills/blob/main/manage.py): Django entrypoint · Standard management command entrypoint. · `manage.py`
- [main.py](https://github.com/shelji/mobi-pills/blob/main/main.py): local launcher · Additional top-level launcher or helper script. · `main.py`
- [WSGI/ASGI](https://github.com/shelji/mobi-pills/blob/main/mobi_pills/wsgi.py): deploy adapters · Production application entrypoints for classic and async deployment. · `mobi_pills/wsgi.py`

### Django core

Project-level routing, settings, and framework glue.

- [Settings](https://github.com/shelji/mobi-pills/blob/main/mobi_pills/settings.py): project config · Django configuration for database, apps, static/media, and environment settings. · `mobi_pills/settings.py`
- [Project URLs](https://github.com/shelji/mobi-pills/blob/main/mobi_pills/urls.py): route map · Top-level routing into the shop app and project views. · `mobi_pills/urls.py`

### Shop app

Primary business boundary for catalog, billing, sales, and stock.

- [Shop URLs](https://github.com/shelji/mobi-pills/blob/main/shop/urls.py): app routes · URL patterns for the shop domain. · `shop/urls.py`
- [Models](https://github.com/shelji/mobi-pills/blob/main/shop/models.py): ORM schema · Relational domain model for products, customers, suppliers, billing, and expenses. · `shop/models.py`
- [Views](https://github.com/shelji/mobi-pills/blob/main/shop/views.py): HTML views · Server-rendered business workflows and page handlers. · `shop/views.py`
- [API views](https://github.com/shelji/mobi-pills/blob/main/shop/api_views.py): JSON endpoints · Async-friendly endpoints for search, updates, and dashboard interactions. · `shop/api_views.py`
- [Serializers](https://github.com/shelji/mobi-pills/blob/main/shop/serializers.py): API schema · Transforms shop models to and from JSON payloads. · `shop/serializers.py`
- [Admin](https://github.com/shelji/mobi-pills/blob/main/shop/admin.py): management UI · Django admin registration for internal maintenance. · `shop/admin.py`
- [Context](https://github.com/shelji/mobi-pills/blob/main/shop/context_processors.py): template context · Shared template data injected into rendered pages. · `shop/context_processors.py`
- [Migrations](https://github.com/shelji/mobi-pills/blob/main/shop/migrations/0001_initial.py): schema history · Database evolution for the shop domain. · `shop/migrations/0001_initial.py`

### Presentation

Server-rendered templates used for the UI.

- [Templates](https://github.com/shelji/mobi-pills/blob/main/templates/base.html): UI pages · Server-rendered pages for dashboard, billing, catalog, and sales. · `templates/base.html`

### Support

Seeding, maintenance, and operational helpers.

- [Seed data](https://github.com/shelji/mobi-pills/blob/main/create_sample_data.py): bootstrap scripts · Scripts that create sample content and dashboard data. · `create_sample_data.py`
- [Image convert](https://github.com/shelji/mobi-pills/blob/main/shop/management/commands/convert_product_images.py): management command · Custom command for product image normalization or migration. · `shop/management/commands/convert_product_images.py`

### Other components

- **Users**: actor · Staff and admins using the shop system.
- **Database**: persistent store · Relational database backing the Django ORM.

## Connections

- Users → Project URLs: browse app · Users enter through the Django site routing.
- manage.py → Settings: loads · Management commands use project settings.
- manage.py → Project URLs: runs · Django management can serve or inspect routed app behavior.
- main.py → WSGI/ASGI: launches · Local or platform-specific startup path.
- WSGI/ASGI → Project URLs: serves · Deployment adapters expose the Django application.
- Project URLs → Shop URLs: delegates · Project routing forwards into the shop app.
- Shop URLs → Views: maps · HTML pages are routed to view handlers.
- Shop URLs → API views: maps · JSON endpoints are routed separately.
- Views → Models: reads/writes · Page workflows use the ORM domain model.
- API views → Serializers: uses · API endpoints serialize and validate payloads.
- API views → Models: reads/writes · API operations act on the same core data.
- Views → Templates: renders · Server-rendered pages are composed from templates.
- Views → Context: injects · Shared page data comes from context processors.
- Templates → Models: displays · Pages present catalog, billing, and sales data.
- Models → Migrations: evolves via · Schema changes are tracked in migrations.
- Models → Database: persists to · Django ORM stores domain data in the database.
- Admin → Models: manages · Admin interface exposes the same domain entities.
- Seed data → Database: seeds · Bootstrap scripts populate demo or sample records.
- Image convert → Models: updates assets · Maintenance command supports product image handling.
- Settings → Database: configures · Project settings define the database connection.
- Settings → Templates: configures · Settings wire template loading and static/media behavior.
- Settings → Admin: enables · Django configuration activates admin and auth surfaces.