parameswar1-hub/mobile-shop

Purpose and Entry Points

Mobile Shop is a self-hosted inventory, purchasing, point-of-sale, invoicing, and reporting system. The user-facing entry point is the React SPA bootstrapped at frontend/src/main.jsx and routed through frontend/src/App.jsx. The API is a Django/DRF service entered via backend/manage.py, deployed through WSGI/ASGI configuration in backend/mobileshop/wsgi.py and backend/mobileshop/asgi.py.

API Composition and Cross-Cutting Policy

Django project settings and top-level API routing centralize application registration and endpoint composition in backend/mobileshop/settings.py and backend/mobileshop/urls.py. Domain apps expose their own URL/view/serializer/model layers, forming REST boundaries between the SPA and persisted business data. Shared pagination, permission, and exception behavior reside in backend/common/pagination.py, backend/common/permissions.py, and backend/common/exceptions.py.

Authentication supports admin and sales-user access, with route protection also enforced in the client through frontend/src/context/AuthContext.jsx and frontend/src/components/ProtectedRoute.jsx.

Product Master Data and Inventory

The catalog is organized around products, categories, brands, and suppliers. Product lookup/filtering and CRUD are defined by backend/apps/products/models.py, backend/apps/products/views.py, and backend/apps/products/filters.py; related master entities live in backend/apps/categories/models.py, backend/apps/brands/models.py, and backend/apps/suppliers/models.py.

Inventory is a distinct consistency boundary. backend/apps/inventory/services.py performs atomic, row-locked stock mutation so concurrent purchase and sale operations do not corrupt quantities. Inventory records and API surfaces are in backend/apps/inventory/models.py and backend/apps/inventory/views.py, supporting a durable before/after stock-change log.

Purchase-to-Stock Flow

Purchase requests enter the purchases API (backend/apps/purchases/urls.py, backend/apps/purchases/views.py) and persist purchase entities in backend/apps/purchases/models.py. The purchase workflow invokes the inventory service to increase stock and record the inventory movement. The SPA presents this workflow through frontend/src/pages/Purchases.jsx.

POS Sale-to-Invoice Flow

POS is the principal transactional flow. The client POS screen (frontend/src/pages/POS.jsx) obtains products by barcode, SKU, or IMEI; scanning hardware/camera integration is encapsulated in frontend/src/components/BarcodeScanner.jsx. Sale creation is handled by backend/apps/sales/views.py and backend/apps/sales/models.py, which decreases inventory through the shared stock boundary and creates an invoice. Invoice persistence, API access, and PDF rendering are in backend/apps/invoices/models.py, backend/apps/invoices/views.py, and backend/apps/invoices/pdf.py.

Reporting, Dashboard, and Audit

Reporting endpoints aggregate sales, purchases, stock, profit, and GST data in backend/apps/reports/views.py, consumed by frontend/src/pages/Reports.jsx. The operational dashboard is represented by frontend/src/pages/Dashboard.jsx. Audit middleware captures API write activity across domain APIs in backend/apps/audit/middleware.py, with log storage and retrieval in backend/apps/audit/models.py and backend/apps/audit/views.py.

Runtime, Deployment, and Operations

Docker Compose orchestrates PostgreSQL, Redis, Django/Gunicorn, the frontend Nginx container, and a shared reverse proxy via docker-compose.yml, backend/Dockerfile, and docker/nginx.conf. The frontend is built as a Vite application (frontend/package.json, frontend/Dockerfile). Environment inputs are defined by .env.example.

Operational entry points include container startup initialization in backend/entrypoint.sh, demo provisioning via backend/apps/users/management/commands/seed_demo_data.py, database backup/restore scripts in scripts/backup.sh and scripts/restore.sh, and Jenkins-driven test/build/deploy/smoke-check automation in Jenkinsfile and scripts/deploy.sh.