# parameswar1-hub/mobile-shop architecture

> Architecture diagram of the GitHub repository parameswar1-hub/mobile-shop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parameswar1-hub/mobile-shop
- Repository: https://github.com/parameswar1-hub/mobile-shop

## Overview

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

Main entry points: [`backend/mobileshop/urls.py`](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/mobileshop/urls.py) (API composition), [`frontend/src/main.jsx`](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/main.jsx) (React SPA), [`docker-compose.yml`](https://github.com/parameswar1-hub/mobile-shop/blob/main/docker-compose.yml) (Compose runtime), [`backend/apps/sales/views.py`](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/sales/views.py) (Sales)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_spa["React SPA<br/>Vite client<br/>[main.jsx]"]
  node_auth["Client auth guard<br/>auth context<br/>[AuthContext.jsx]"]
  node_pos["POS screen<br/>sale UI<br/>[POS.jsx]"]
  node_scanner["Barcode scanner<br/>scan integration<br/>[BarcodeScanner.jsx]"]
  node_purchases_ui["Purchases screen<br/>purchase UI<br/>[Purchases.jsx]"]
  node_reports_ui["Reports &amp; dashboard<br/>analytics UI<br/>[Reports.jsx]"]
end

subgraph group_api["Django API"]
  node_api_router["API composition<br/>Django routing<br/>[urls.py]"]
  node_api_policy["Shared API policy<br/>DRF policy<br/>[permissions.py]"]
end

subgraph group_domains["Business domains"]
  node_catalog["Catalog &amp; master data<br/>product API<br/>[views.py]"]
  node_purchases["Purchases<br/>purchase API<br/>[views.py]"]
  node_sales["Sales<br/>sale API<br/>[views.py]"]
  node_inventory{{"Inventory service<br/>stock consistency<br/>[services.py]"}}
  node_invoices["Invoices &amp; PDFs<br/>invoice API<br/>[pdf.py]"]
  node_reporting["Reporting<br/>report API<br/>[views.py]"]
  node_audit["Audit trail<br/>audit middleware<br/>[middleware.py]"]
end

subgraph group_operations["Runtime &amp; operations"]
  node_database[("PostgreSQL<br/>persistent store")]
  node_container_runtime["Compose runtime<br/>container orchestration<br/>[docker-compose.yml]"]
  node_backend_entry["Django deployment<br/>WSGI/ASGI service<br/>[wsgi.py]"]
  node_frontend_build["Frontend container<br/>Vite build"]
  node_automation["CI/CD automation<br/>Jenkins pipeline"]
  node_backup_restore["Backup &amp; restore<br/>database operations<br/>[backup.sh]"]
end

node_spa -->|"protects routes"| node_auth
node_spa -->|"routes to"| node_pos
node_spa -->|"routes to"| node_purchases_ui
node_spa -->|"routes to"| node_reports_ui
node_scanner -->|"scan input"| node_pos
node_pos -->|"sale and lookup requests"| node_api_router
node_purchases_ui -->|"purchase requests"| node_api_router
node_reports_ui -->|"report requests"| node_api_router
node_api_router -->|"applies"| node_api_policy
node_api_router -->|"routes"| node_catalog
node_api_router -->|"routes"| node_purchases
node_api_router -->|"routes"| node_sales
node_api_router -->|"routes"| node_reporting
node_api_router -.->|"write activity"| node_audit
node_purchases -->|"receive stock"| node_inventory
node_sales -->|"decrease stock"| node_inventory
node_sales -->|"creates invoice"| node_invoices
node_reporting -->|"aggregates"| node_database
node_catalog -->|"persists"| node_database
node_inventory -->|"stock and movements"| node_database
node_invoices -->|"persists"| node_database
node_audit -->|"stores logs"| node_database
node_container_runtime -->|"runs"| node_backend_entry
node_container_runtime -->|"runs"| node_frontend_build
node_container_runtime -->|"runs"| node_database
node_automation -->|"deploys"| node_container_runtime
node_backup_restore -->|"backs up / restores"| node_database

click node_spa "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/main.jsx"
click node_auth "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/context/AuthContext.jsx"
click node_pos "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/pages/POS.jsx"
click node_scanner "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/components/BarcodeScanner.jsx"
click node_purchases_ui "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/pages/Purchases.jsx"
click node_reports_ui "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/pages/Reports.jsx"
click node_api_router "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/mobileshop/urls.py"
click node_api_policy "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/common/permissions.py"
click node_catalog "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/products/views.py"
click node_purchases "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/purchases/views.py"
click node_sales "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/sales/views.py"
click node_inventory "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/inventory/services.py"
click node_invoices "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/invoices/pdf.py"
click node_reporting "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/reports/views.py"
click node_audit "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/audit/middleware.py"
click node_container_runtime "https://github.com/parameswar1-hub/mobile-shop/blob/main/docker-compose.yml"
click node_backend_entry "https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/mobileshop/wsgi.py"
click node_frontend_build "https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/Dockerfile"
click node_automation "https://github.com/parameswar1-hub/mobile-shop/blob/main/Jenkinsfile"
click node_backup_restore "https://github.com/parameswar1-hub/mobile-shop/blob/main/scripts/backup.sh"

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_spa,node_auth,node_pos,node_scanner,node_purchases_ui,node_reports_ui toneBlue
class node_api_router,node_api_policy toneAmber
class node_catalog,node_purchases,node_sales,node_inventory,node_invoices,node_reporting,node_audit toneMint
class node_database,node_container_runtime,node_backend_entry,node_frontend_build,node_automation,node_backup_restore toneRose
```

## Components

### React client

- [React SPA](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/main.jsx): Vite client · User-facing application shell and routes. · `frontend/src/main.jsx`
- [Client auth guard](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/context/AuthContext.jsx): auth context · Maintains session state and protects client routes. · `frontend/src/context/AuthContext.jsx`
- [POS screen](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/pages/POS.jsx): sale UI · Drives barcode/SKU/IMEI product lookup and sale creation. · `frontend/src/pages/POS.jsx`
- [Barcode scanner](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/components/BarcodeScanner.jsx): scan integration · `frontend/src/components/BarcodeScanner.jsx`
- [Purchases screen](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/pages/Purchases.jsx): purchase UI · `frontend/src/pages/Purchases.jsx`
- [Reports & dashboard](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/src/pages/Reports.jsx): analytics UI · `frontend/src/pages/Reports.jsx`

### Django API

- [API composition](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/mobileshop/urls.py): Django routing · Registers domain APIs and shared API policy. · `backend/mobileshop/urls.py`
- [Shared API policy](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/common/permissions.py): DRF policy · Pagination, permissions, and exception behavior. · `backend/common/permissions.py`

### Business domains

- [Catalog & master data](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/products/views.py): product API · Products, categories, brands, suppliers, and filtering. · `backend/apps/products/views.py`
- [Purchases](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/purchases/views.py): purchase API · Persists purchases and initiates stock receipt. · `backend/apps/purchases/views.py`
- [Sales](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/sales/views.py): sale API · Creates POS sales and coordinates stock reduction. · `backend/apps/sales/views.py`
- [Inventory service](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/inventory/services.py): stock consistency · Atomically row-locks stock mutations and records movements. · `backend/apps/inventory/services.py`
- [Invoices & PDFs](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/invoices/pdf.py): invoice API · Persists invoices and renders invoice PDFs. · `backend/apps/invoices/pdf.py`
- [Reporting](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/reports/views.py): report API · Aggregates sales, purchases, stock, profit, and GST. · `backend/apps/reports/views.py`
- [Audit trail](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/apps/audit/middleware.py): audit middleware · Captures API write activity for storage and retrieval. · `backend/apps/audit/middleware.py`

### Runtime & operations

- **PostgreSQL**: persistent store · Durable business, inventory, invoice, and audit data.
- [Compose runtime](https://github.com/parameswar1-hub/mobile-shop/blob/main/docker-compose.yml): container orchestration · Runs PostgreSQL, Redis, Django/Gunicorn, Nginx, and proxy. · `docker-compose.yml`
- [Django deployment](https://github.com/parameswar1-hub/mobile-shop/blob/main/backend/mobileshop/wsgi.py): WSGI/ASGI service · Backend process entry configuration. · `backend/mobileshop/wsgi.py`
- [Frontend container](https://github.com/parameswar1-hub/mobile-shop/blob/main/frontend/Dockerfile): Vite build · Builds and serves the SPA through Nginx. · `frontend/Dockerfile`
- [CI/CD automation](https://github.com/parameswar1-hub/mobile-shop/blob/main/Jenkinsfile): Jenkins pipeline · Tests, builds, deploys, and smoke-checks releases. · `Jenkinsfile`
- [Backup & restore](https://github.com/parameswar1-hub/mobile-shop/blob/main/scripts/backup.sh): database operations · `scripts/backup.sh`

## Connections

- React SPA → Client auth guard: protects routes
- React SPA → POS screen: routes to
- React SPA → Purchases screen: routes to
- React SPA → Reports & dashboard: routes to
- Barcode scanner → POS screen: scan input
- POS screen → API composition: sale and lookup requests
- Purchases screen → API composition: purchase requests
- Reports & dashboard → API composition: report requests
- API composition → Shared API policy: applies
- API composition → Catalog & master data: routes
- API composition → Purchases: routes
- API composition → Sales: routes
- API composition → Reporting: routes
- API composition → Audit trail: write activity
- Purchases → Inventory service: receive stock
- Sales → Inventory service: decrease stock
- Sales → Invoices & PDFs: creates invoice
- Reporting → PostgreSQL: aggregates
- Catalog & master data → PostgreSQL: persists
- Inventory service → PostgreSQL: stock and movements
- Invoices & PDFs → PostgreSQL: persists
- Audit trail → PostgreSQL: stores logs
- Compose runtime → Django deployment: runs
- Compose runtime → Frontend container: runs
- Compose runtime → PostgreSQL: runs
- CI/CD automation → Compose runtime: deploys
- Backup & restore → PostgreSQL: backs up / restores