How shelji/mobi-pills works
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: models.py Models · settings.py Settings · views.py Views · urls.py Project URLs
Components 18
Entrypoints
Process launchers and deployment hooks.
Django core
Project-level routing, settings, and framework glue.
- Settings · Django configuration for database, apps, static/media, and environment settings.
mobi_pills/settings.py - Project URLs · 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 · URL patterns for the shop domain.
shop/urls.py - Models · Relational domain model for products, customers, suppliers, billing, and expenses.
shop/models.py - Views · Server-rendered business workflows and page handlers.
shop/views.py - API views · Async-friendly endpoints for search, updates, and dashboard interactions.
shop/api_views.py - Serializers · Transforms shop models to and from JSON payloads.
shop/serializers.py - Admin · Django admin registration for internal maintenance.
shop/admin.py - Context · Shared template data injected into rendered pages.
shop/context_processors.py - Migrations · Database evolution for the shop domain.
shop/migrations/0001_initial.py
Presentation
Server-rendered templates used for the UI.
- Templates · Server-rendered pages for dashboard, billing, catalog, and sales.
templates/base.html
Support
Seeding, maintenance, and operational helpers.
- Seed data · Scripts that create sample content and dashboard data.
create_sample_data.py - Image convert · Custom command for product image normalization or migration.
shop/management/commands/convert_product_images.py
Other components
- Users · Staff and admins using the shop system.
- Database · Relational database backing the Django ORM.
Connections 22
- 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.