{"id":48683130,"url":"https://github.com/abdullahbakir97/stock-manager","last_synced_at":"2026-06-13T17:00:46.274Z","repository":{"id":347481461,"uuid":"1194200470","full_name":"AbdullahBakir97/Stock-Manager","owner":"AbdullahBakir97","description":"Professional desktop inventory management for Windows — local-first SQLite store, barcode-aware, multi-user with role separation.","archived":false,"fork":false,"pushed_at":"2026-06-10T16:27:41.000Z","size":6009,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T17:15:24.756Z","etag":null,"topics":["desktop-app","inventory-management","offline","pyqt6","python","sqlite","stock-manager","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AbdullahBakir97.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T03:21:49.000Z","updated_at":"2026-05-26T15:39:35.000Z","dependencies_parsed_at":"2026-03-28T09:01:28.599Z","dependency_job_id":null,"html_url":"https://github.com/AbdullahBakir97/Stock-Manager","commit_stats":null,"previous_names":["abdullahbakir97/stock-manager"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/AbdullahBakir97/Stock-Manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdullahBakir97%2FStock-Manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdullahBakir97%2FStock-Manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdullahBakir97%2FStock-Manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdullahBakir97%2FStock-Manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbdullahBakir97","download_url":"https://codeload.github.com/AbdullahBakir97/Stock-Manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdullahBakir97%2FStock-Manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34292326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-app","inventory-management","offline","pyqt6","python","sqlite","stock-manager","windows"],"created_at":"2026-04-11T03:17:13.958Z","updated_at":"2026-06-13T17:00:46.268Z","avatar_url":"https://github.com/AbdullahBakir97.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"stock-manager/src/files/img/icon_cube.png\" alt=\"Stock Manager Pro\" width=\"80\"/\u003e\n\n# Stock Manager Pro\n\n**Professional desktop inventory management for Windows**\n\nBuilt with Python 3.11 · PyQt6 · SQLite · Offline-first · Optional cloud sync · Multilingual\n\n[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)](https://python.org)\n[![PyQt6](https://img.shields.io/badge/PyQt6-6.10-41CD52?style=flat-square)](https://riverbankcomputing.com/software/pyqt/)\n[![SQLite](https://img.shields.io/badge/SQLite-Schema_V23-003B57?style=flat-square\u0026logo=sqlite)](https://sqlite.org)\n[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)\n[![Version](https://img.shields.io/badge/Version-2.6.4-10B981?style=flat-square)](https://github.com/AbdullahBakir97/Stock-manager/releases)\n[![Platform](https://img.shields.io/badge/Platform-Windows_10%2F11-0078D4?style=flat-square\u0026logo=windows)](https://github.com/AbdullahBakir97/Stock-manager/releases)\n\n[Features](#-features) · [Screenshots](#-screenshots) · [Installation](#-installation) · [Architecture](#-architecture) · [Project Structure](#-project-structure) · [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\nStock Manager Pro is a professional, offline-first desktop inventory management application for small-to-medium repair shops, retail stores, and warehouses. It ships with a complete business operations suite — a full POS terminal, purchase-order lifecycle, stocktake audits, price lists, supplier CRM, multi-location stock, **IMEI-level phone-unit tracking**, and **14 branded PDF reports** — all built on a zero-freeze async engine with a clean controller architecture. Data stays local by default, with **optional multi-PC cloud sync** via Turso when you need it.\n\n\u003e **Designed for resale.** Every architecture decision prioritises reusability and extensibility so the codebase can serve as the foundation for a general-purpose stock management platform.\n\n---\n\n## ✨ Features\n\n### Core Inventory\n- Unified inventory across categories, part types, phone models, and colour variants\n- **Matrix grid view** — spreadsheet-style bulk stock across model × part-type × colour, with a frozen model column, sticky headers, and per-part-type value totals\n- **Phone units (IMEI tracking)** — track whole devices individually by IMEI: storage, condition, battery %, buy/sell price, status (in stock / sold / reserved), barcode labels, sold-history and a full audit log *(optional white-label module)*\n- Stock In / Out / Adjust with timestamped notes and full undo / redo\n- Per-item minimum-stock thresholds with real-time low-stock alerts\n- Product photos, expiry dates, and warranty tracking per item\n- Barcode generation (Code128/EAN) and USB scanner interception\n\n### Business Modules\n| Module | Highlights |\n|---|---|\n| **Sales / POS** | Cart-based POS, customer lookup, discounts, PDF receipts, edit/void with automatic stock reversal |\n| **Phones (IMEI)** | Whole-device inventory by IMEI — brand × model stock grid, scan-to-sell, reserve, barcode labels, sold history |\n| **Purchase Orders** | DRAFT → SENT → PARTIAL → RECEIVED lifecycle, auto stock-in on receipt |\n| **Returns** | RESTOCK or WRITE_OFF actions, refund tracking, sale linkage |\n| **Suppliers** | Supplier CRM, cost prices, lead days, linked inventory items |\n| **Price Lists** | Create, draft, activate and bulk-apply pricing configurations |\n| **Audit / Stocktake** | Cycle-based counted vs system qty comparison with variance reporting |\n| **Customers** | Customer profiles linked to sales and purchase history |\n| **Locations** | Multi-location stock with transfers between warehouse positions |\n| **Reports** | 14 branded PDF reports — inventory, valuation (at cost), low stock, transactions, sales, category performance, audit, **phone inventory \u0026 sold history**, barcode labels, and more |\n\n### Platform\n- **Zero-freeze UI** — every DB operation runs off the main thread via `WorkerPool`\n- **Optional cloud sync** — share one live dataset across multiple PCs via Turso (libSQL) over the HTTP API; pure-stdlib client, no server to run, opt-in per install\n- **White-label modules** — shop-specific features (e.g. the Phones / IMEI tracker) are opt-in per install via Shop Settings → Modules\n- **Multilingual** — English, German (DE), Arabic (AR) with live switching and full RTL layout\n- **Four themes** — Dark, Light, Pro Dark (emerald/charcoal), Pro Light (emerald/white) — toggle updates all components\n- **Excel-like zoom** — Ctrl+Scroll / Ctrl+Plus/Minus zoom (50–200%) with footer slider\n- **Auto-updater** — manifest-based version check with SHA256 verification; CI/CD auto-release\n- **Auto-backup** — scheduled backup with configurable retention\n- **Optimised database** — thread-local connection pool, batch inserts, performance indexes, tuned pragmas\n- **Undo / redo** — reverse any stock or phone-status operation\n- **Tested \u0026 CI-released** — pytest suite over repositories, services and the full migration chain\n- **Offline-first** — local SQLite (WAL), no telemetry; cloud sync is strictly opt-in\n\n---\n\n## 📸 Screenshots\n\n\u003e Screenshots use a demo **Galaxy@Phone** dataset.\n\n### Analytics Dashboard\nReal-time KPI cards (stock value at cost, revenue, transactions, low stock), a stock-health donut, value-by-brand bars, and a brand × part-type valuation pivot — all loaded asynchronously off the UI thread.\n\n![Analytics Dashboard](files/img/scr-dashboard.png)\n\n---\n\n### Matrix View\nThe core workflow — spreadsheet-style bulk stock across model × part-type × colour, with a frozen model column, per-part-type value totals, and Low / Out / Reorder filters.\n\n![Matrix View](files/img/scr-displays.png)\n\n---\n\n### Inventory\nSearchable, filterable product table with KPI overview cards (units, low / out of stock, inventory value), status badges, and inline +1 / −1 quick-stock actions.\n\n![Inventory](files/img/scr-inventory-v2.png)\n\n---\n\n### Phones — IMEI tracking\nWhole-device inventory tracked by IMEI: a brand × model stock grid by storage, KPIs (total / in stock / sold / avg battery / stock value), scan-to-sell, reserve, and barcode labels. *(Optional white-label module.)*\n\n![Phones](files/img/scr-phones.png)\n\n---\n\n### Sales \u0026 POS\nCart-based point-of-sale with product picker, customer lookup, discounts, automatic PDF receipts, and edit / void with stock reversal.\n\n![Sales \u0026 POS](files/img/scr-sales.png)\n\n---\n\n### Reports\n14 professional, branded PDF reports for **parts and phones** — inventory, valuation (at cost), low stock, transactions, sales, category performance, audit sheets, phone inventory \u0026 sold history, expiring stock, and barcode labels.\n\n![Reports](files/img/scr-reports.png)\n\n---\n\n### Transactions\nPaginated stock-movement audit log with an IN / OUT / ADJUST / Net summary strip, debounced filters, and Load-More pagination.\n\n![Transactions](files/img/scr-transactions.png)\n\n---\n\n### Purchase Orders\nFull PO lifecycle from DRAFT through SENT → PARTIAL → RECEIVED. Receiving a PO automatically triggers a stock-in.\n\n![Purchase Orders](files/img/scr-purchase-orders.png)\n\n---\n\n### Suppliers\nSupplier CRM with contact details, rating, linked inventory items, and open purchase-order count per supplier.\n\n![Suppliers](files/img/scr-suppliers.png)\n\n---\n\n### Audit \u0026 Stocktake\nCycle-based stocktake with item-by-item counted-qty entry, system-vs-counted variance reporting, and a completion summary.\n\n![Audit](files/img/scr-audit.png)\n\n---\n\n### Price Lists\nCreate and manage pricing configurations; apply a bulk percentage markup or push a list straight to live inventory.\n\n![Price Lists](files/img/scr-price-lists.png)\n\n---\n\n### Returns\nProcess returns with RESTOCK or WRITE_OFF actions — reverses the original transaction and records the refund amount.\n\n![Returns](files/img/scr-returns.png)\n\n---\n\n### Quick Scan\nUSB barcode-scanner interception with command barcodes (TAKEOUT / INSERT / CONFIRM) for hands-free stock counting.\n\n![Quick Scan](files/img/scr-quickscan.png)\n\n---\n\n### Barcode Generator\nGenerate and export Code128 / EAN barcodes; batch-print labels for new stock.\n\n![Barcode Generator](files/img/scr-barcode.png)\n\n---\n\n## 🖥️ System Requirements\n\n| | |\n|---|---|\n| **OS** | Windows 10 or Windows 11 (64-bit) |\n| **RAM** | 512 MB minimum · 2 GB recommended |\n| **Disk** | 250 MB application + database storage |\n| **Python** | 3.11+ (development only) |\n| **Admin rights** | Not required |\n\n---\n\n## 📦 Installation\n\n### Option A — Pre-built Executable (Recommended)\n\n1. Download `StockManagerPro.zip` from the [latest release](https://github.com/AbdullahBakir97/Stock-manager/releases)\n2. Extract to any folder (e.g. `C:\\Apps\\StockManagerPro\\`)\n3. Run `StockManagerPro.exe`\n\nData is stored at `%LOCALAPPDATA%\\StockPro\\StockManagerPro\\stock_manager.db` — no installation wizard, no admin rights needed.\n\n### Option B — Run from Source\n\n**Prerequisites:** Python 3.11+, Git, Windows 10/11\n\n```bash\ngit clone https://github.com/AbdullahBakir97/Stock-manager.git\ncd Stock-manager\n\npython -m venv venv\nvenv\\Scripts\\activate\n\npip install -r requirements.txt\n\ncd src/files\npython main.py\n```\n\n---\n\n## 🚀 Quick Start\n\n| Task | How |\n|---|---|\n| First-time setup | Complete the Setup Wizard on first launch |\n| Add a product | `Ctrl+N` or **+ Add Product** button |\n| Stock In | Select product → `Ctrl+I` |\n| Stock Out | Select product → `Ctrl+O` |\n| Adjust stock | Select product → `Ctrl+J` |\n| Open POS | Navigate to **Sales / POS** → New Sale |\n| Generate barcode | Right-click product → Generate Barcode or `Ctrl+B` |\n| Export PDF report | Navigate to **Reports** or `Ctrl+P` |\n| Admin settings | `Ctrl+Alt+A` or the ⚙ header icon |\n| Switch language | Header language switcher (EN / DE / AR) |\n| Undo last operation | Right-click transaction → Undo |\n| Force refresh | `F5` |\n\n---\n\n## 🔨 Build Instructions\n\n```bash\ncd Stock-manager\npyinstaller src/StockManagerPro.spec --noconfirm\n# Output: src/dist/StockManagerPro/StockManagerPro.exe\n```\n\nBuild time ~3–5 minutes. Output ~180 MB (includes Python runtime, PyQt6, all dependencies).\n\n---\n\n## 🏗️ Architecture\n\n### Layer Structure\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│  UI Layer  —  app/ui/                                        │\n│  pages/ · components/ · dialogs/ · tabs/ · controllers/     │\n├──────────────────────────────────────────────────────────────┤\n│  Async Engine  —  app/ui/workers/                            │\n│  WorkerPool · DataWorker · UpdateWorker                      │\n├──────────────────────────────────────────────────────────────┤\n│  Service Layer  —  app/services/                             │\n│  StockService · SaleService · AuditService · …  (21 total)  │\n├──────────────────────────────────────────────────────────────┤\n│  Repository Layer  —  app/repositories/                      │\n│  ItemRepo · SaleRepo · AuditRepo · …  (13 total)            │\n├──────────────────────────────────────────────────────────────┤\n│  Model Layer  —  app/models/                                 │\n│  InventoryItem · Sale · PurchaseOrder · …  (13 total)       │\n├──────────────────────────────────────────────────────────────┤\n│  Core Layer  —  app/core/                                    │\n│  Database · Theme · i18n · Config · Logger · Colors         │\n│  SQLite WAL · Schema V23 · 27 tables · optional Turso sync  │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### Zero-Freeze Async Engine\n\nThe `WorkerPool` singleton (backed by `QThreadPool`) routes every DB operation off the main thread. The main thread only ever applies results — it never queries:\n\n```python\n# Background fetch → main-thread apply, keyed and cancellable\nPOOL.submit(\"analytics_refresh\", self._fetch_all_data, self._apply_all_data)\n\n# Debounced for filter inputs — cancels previous if fired again within delay\nPOOL.submit_debounced(\"txn_filter\", self.fetch_filtered, self.load_results, delay_ms=100)\n\n# Theme changes deferred to next event-loop tick — eliminates freeze on toggle\nQTimer.singleShot(0, lambda: self._apply_ss(root, stylesheet))\n```\n\n### Controller Pattern\n\n`main_window.py` was decomposed from 2,263 lines to 572 by extracting seven purpose-built controllers:\n\n| Controller | Responsibility |\n|---|---|\n| `NavController` | Registry-based page navigation, sidebar toggle, matrix tab lifecycle |\n| `StartupController` | Two-phase async startup — KPIs first, inventory table second |\n| `UpdateController` | Manifest-based version check, update badge wiring |\n| `AlertController` | Low-stock alert counts, notification panel refresh |\n| `StockOpsController` | IN / OUT / ADJUST dispatch, dialog lifecycle |\n| `BulkOpsController` | Bulk edit, bulk price change |\n| `InventoryOpsController` | Inventory filter, selection, detail bar sync |\n\n### Database — Schema V23\n\nFull automatic migration chain from V1 through V23 runs on every startup:\n\n| Migration | What was added |\n|---|---|\n| V3 | Shop config keys, `setup_complete` flag |\n| V4 | Consolidate `products` + `stock_entries` → `inventory_items` |\n| V5 | Quick Scan command barcodes in `app_config` |\n| V6 | `part_type_colors`; UNIQUE(model, part_type, color) constraint; drop all legacy tables |\n| V7 | `image_path` column on `inventory_items` |\n| V8 | `expiry_date`, `warranty_date`; `locations`, `location_stock`, `stock_transfers` |\n| V9 | `sales`, `sale_items` tables |\n| V10 | `customers` table; `customer_id` FK on `sales` |\n| V11 | `purchase_orders`, `purchase_order_lines`, `returns` |\n| V12 | `suppliers` with rating; `supplier_items`; `inventory_audits`; `audit_lines`; `price_lists`; `price_list_items` |\n| V13 | `model_part_type_colors` — per-model product colour overrides |\n| V14 | Performance indexes on `inventory_items` (active, stock, model+pt, model+pt+color) |\n| V15 | `part_types.default_price`; `scan_invoices`, `scan_invoice_items` (Quick Scan invoice history) |\n| V16 | `cost_price` on `inventory_items` (cost-basis valuation) |\n| V18 | Hot-path indexes (`phone_models.brand`, `part_type_colors`, `model_part_type_colors`) |\n| V19–V21 | Barcode round-trip fixes for German (QWERTZ) keyboards (`+`→`P`, `Y`↔`Z`, `/`→`-`) with data migrations |\n| V22 | `phones` — IMEI-tracked phone units |\n| V23 | `phone_transactions` — phone-unit audit log |\n\n**27 tables total:** `app_config`, `categories`, `part_types`, `phone_models`, `part_type_colors`, `model_part_type_colors`, `inventory_items`, `inventory_transactions`, `suppliers`, `supplier_items`, `locations`, `location_stock`, `stock_transfers`, `customers`, `sales`, `sale_items`, `purchase_orders`, `purchase_order_lines`, `returns`, `inventory_audits`, `audit_lines`, `price_lists`, `price_list_items`, `scan_invoices`, `scan_invoice_items`, `phones`, `phone_transactions`\n\n---\n\n## 📁 Project Structure\n\n```\nStock-manager/\n└── src/\n    ├── StockManagerPro.spec              # PyInstaller build config\n    ├── README.md\n    └── files/\n        ├── main.py                       # Entry point\n        ├── requirements.txt\n        ├── app/\n        │   ├── core/\n        │   │   ├── database.py           # Schema V23, migrations V1→V23, Turso HTTP client\n        │   │   ├── theme.py              # 4 themes, zero-freeze deferred apply\n        │   │   ├── i18n.py               # EN / DE / AR translations\n        │   │   ├── colors.py             # 24-colour PALETTE\n        │   │   ├── version.py            # APP_VERSION, UPDATE_MANIFEST_URL\n        │   │   ├── health.py             # DB health checks\n        │   │   ├── logger.py             # Structured rotating logger\n        │   │   ├── config.py             # App config key-value store\n        │   │   ├── icon_utils.py         # SVG icon loader\n        │   │   └── scan_config.py        # Barcode scanner configuration\n        │   │\n        │   ├── models/                   # 13 domain dataclasses\n        │   │   ├── item.py               # InventoryItem (core model)\n        │   │   ├── transaction.py        # StockTransaction\n        │   │   ├── sale.py               # Sale, SaleItem\n        │   │   ├── purchase_order.py     # PurchaseOrder, POLineItem\n        │   │   ├── return_item.py        # Return, ReturnAction\n        │   │   ├── supplier.py           # Supplier\n        │   │   ├── customer.py           # Customer\n        │   │   ├── audit.py              # AuditCycle, AuditLine\n        │   │   ├── price_list.py         # PriceList, PriceListItem\n        │   │   ├── location.py           # Location, LocationStock\n        │   │   ├── category.py           # Category\n        │   │   ├── phone_model.py        # PhoneModel\n        │   │   └── scan_session.py       # ScanSession\n        │   │\n        │   ├── repositories/             # 13 SQL-only data access repos\n        │   │   ├── item_repo.py\n        │   │   ├── transaction_repo.py\n        │   │   ├── sale_repo.py\n        │   │   ├── purchase_order_repo.py\n        │   │   ├── return_repo.py\n        │   │   ├── supplier_repo.py\n        │   │   ├── customer_repo.py\n        │   │   ├── audit_repo.py\n        │   │   ├── price_list_repo.py\n        │   │   ├── location_repo.py\n        │   │   ├── category_repo.py\n        │   │   ├── model_repo.py\n        │   │   └── base.py\n        │   │\n        │   ├── services/                 # 21 business-logic services\n        │   │   ├── stock_service.py      # IN / OUT / ADJUST / undo\n        │   │   ├── alert_service.py      # StockAlertCounts\n        │   │   ├── sale_service.py       # Cart checkout, deduction\n        │   │   ├── receipt_service.py    # PDF receipt via fpdf2\n        │   │   ├── purchase_order_service.py\n        │   │   ├── return_service.py\n        │   │   ├── supplier_service.py\n        │   │   ├── customer_service.py\n        │   │   ├── audit_service.py\n        │   │   ├── price_list_service.py # apply_price_list() bulk update\n        │   │   ├── location_service.py\n        │   │   ├── undo_service.py       # Reverse last transaction\n        │   │   ├── backup_service.py     # Retention-managed backup\n        │   │   ├── backup_scheduler.py   # 5-min QTimer off main thread\n        │   │   ├── update_service.py     # Manifest check + download\n        │   │   ├── image_service.py      # Product photo import/resize\n        │   │   ├── export_service.py     # CSV / JSON export\n        │   │   ├── import_service.py     # CSV import + validation\n        │   │   ├── report_service.py     # PDF reports\n        │   │   ├── barcode_gen_service.py\n        │   │   └── scan_session_service.py\n        │   │\n        │   └── ui/\n        │       ├── main_window.py        # 572 lines (was 2,263)\n        │       ├── helpers.py\n        │       ├── delegates.py\n        │       │\n        │       ├── workers/              # Async engine\n        │       │   ├── worker_pool.py    # POOL singleton, keyed cancellation\n        │       │   ├── data_worker.py    # Generic background fetch\n        │       │   └── update_worker.py  # Version-check worker\n        │       │\n        │       ├── controllers/          # 7 purpose-built controllers\n        │       │   ├── nav_controller.py\n        │       │   ├── startup_controller.py\n        │       │   ├── update_controller.py\n        │       │   ├── alert_controller.py\n        │       │   ├── stock_ops.py\n        │       │   ├── bulk_ops.py\n        │       │   └── inventory_ops.py\n        │       │\n        │       ├── pages/                # 11 full-page views\n        │       │   ├── inventory_page.py\n        │       │   ├── transactions_page.py\n        │       │   ├── analytics_page.py\n        │       │   ├── sales_page.py\n        │       │   ├── purchase_orders_page.py\n        │       │   ├── returns_page.py\n        │       │   ├── suppliers_page.py\n        │       │   ├── price_lists_page.py\n        │       │   ├── audit_page.py\n        │       │   ├── reports_page.py\n        │       │   └── barcode_gen_page.py\n        │       │\n        │       ├── components/           # 23 reusable UI components\n        │       │   ├── dashboard_widget.py   # KPI summary cards\n        │       │   ├── header_bar.py         # Glass search bar\n        │       │   ├── footer_bar.py         # Status + filter hint\n        │       │   ├── sidebar.py            # Nav button registry\n        │       │   ├── theme_toggle.py       # Animated sun/moon toggle\n        │       │   ├── language_switcher.py  # Animated dropdown\n        │       │   ├── update_banner.py      # Slide-in update panel\n        │       │   ├── notification_panel.py # Alert counts + badge\n        │       │   ├── product_detail.py     # Product detail panel\n        │       │   ├── product_detail_bar.py # Sparkline + quick actions\n        │       │   ├── product_table.py      # Responsive columns\n        │       │   ├── transaction_table.py\n        │       │   ├── responsive_table.py\n        │       │   ├── toast.py              # Floating notifications\n        │       │   ├── loading_overlay.py\n        │       │   ├── splash_screen.py      # Geometric cube + version badge\n        │       │   ├── charts.py\n        │       │   ├── empty_state.py\n        │       │   ├── collapsible_section.py\n        │       │   ├── mini_txn_list.py\n        │       │   ├── barcode_line_edit.py\n        │       │   ├── filter_bar.py\n        │       │   └── matrix_widget.py      # Frozen col, zoom, per-model colors\n        │       │\n        │       ├── tabs/\n        │       │   ├── matrix_tab.py\n        │       │   ├── quick_scan_tab.py\n        │       │   ├── stock_ops_tab.py\n        │       │   └── base_tab.py\n        │       │\n        │       └── dialogs/\n        │           ├── product_dialogs.py       # ModernDialog, ColorPicker, StockOp\n        │           ├── dialog_base.py\n        │           ├── bulk_price_dialog.py\n        │           ├── price_list_dialogs.py\n        │           ├── help_dialog.py\n        │           ├── matrix_dialogs.py\n        │           ├── barcode_assign_dialog.py\n        │           ├── setup_wizard.py\n        │           └── admin/                   # 14-panel admin dialog\n        │               ├── admin_dialog.py\n        │               ├── shop_settings_panel.py\n        │               ├── categories_panel.py\n        │               ├── part_types_panel.py\n        │               ├── models_panel.py\n        │               ├── scan_settings_panel.py\n        │               ├── backup_panel.py\n        │               ├── import_export_panel.py\n        │               ├── db_tools_panel.py\n        │               ├── suppliers_panel.py\n        │               ├── locations_panel.py\n        │               ├── customers_panel.py\n        │               ├── about_panel.py\n        │               └── color_picker_widget.py\n        │\n        ├── tests/                        # 30+ pytest modules\n        │   ├── conftest.py               # In-memory SQLite fixtures\n        │   ├── test_database.py          # Schema creation\n        │   ├── test_migration.py         # Full V1→V12 chain\n        │   ├── test_item_repo.py\n        │   ├── test_transaction_repo.py\n        │   ├── test_stock_service.py\n        │   ├── test_sale_service.py\n        │   ├── test_audit_service.py\n        │   ├── test_purchase_order_service.py\n        │   ├── test_return_service.py\n        │   ├── test_supplier_service.py\n        │   ├── test_customer_service.py\n        │   ├── test_price_list_service.py\n        │   ├── test_backup_service.py\n        │   ├── test_undo_service.py\n        │   ├── test_export_service.py\n        │   └── … (30+ total)\n        │\n        └── img/                          # Screenshots \u0026 assets\n            ├── icon_cube.ico             # App icon (multi-resolution)\n            ├── icon_cube.png             # 256px isometric cube\n            ├── icon_cube_16.png\n            ├── icon_cube_32.png\n            ├── icon_cube_48.png\n            ├── icon_cube_64.png\n            ├── icon_cube_128.png\n            ├── icon_cube_256.png\n            ├── scr-dashboard.png\n            ├── scr-inventory-v2.png\n            ├── scr-sales.png\n            ├── scr-analytics.png\n            ├── scr-transactions.png\n            ├── scr-purchase-orders.png\n            ├── scr-audit.png\n            ├── scr-price-lists.png\n            ├── scr-suppliers.png\n            ├── scr-returns.png\n            ├── scr-admin.png\n            ├── scr-admin-about.png\n            ├── scr-displays.png\n            ├── scr-quickscan.png\n            ├── scr-barcode.png\n            └── icons/\n```\n\n---\n\n## 🛠️ Tech Stack\n\n| Layer | Technology | Purpose |\n|---|---|---|\n| UI Framework | **PyQt6 6.10** | Cross-platform desktop GUI |\n| Database | **SQLite 3** WAL + FK | Local relational storage |\n| PDF | **fpdf2 2.8** + **PyMuPDF 1.27** | Reports and receipts |\n| Barcodes | **python-barcode 0.16** | Code128 / EAN generation |\n| Images | **Pillow 12.1** | Product photos, icon handling |\n| Packaging | **PyInstaller 6.19** | Windows executable |\n| Testing | **pytest** | 30+ modules, in-memory fixtures |\n\n```\nPyQt6==6.10.2\nPillow==12.1.1\nfpdf2==2.8.7\nPyMuPDF==1.27.2.2\npython-barcode==0.16.1\ndefusedxml==0.7.1\nPyInstaller==6.19.0\n```\n\n---\n\n## ⌨️ Keyboard Shortcuts\n\n| Action | Shortcut |\n|---|---|\n| New product | `Ctrl+N` |\n| Stock In | `Ctrl+I` |\n| Stock Out | `Ctrl+O` |\n| Adjust stock | `Ctrl+J` |\n| Search | `Ctrl+F` |\n| Delete product | `Del` |\n| Generate barcode | `Ctrl+B` |\n| Export PDF report | `Ctrl+P` |\n| Zoom in | `Ctrl+=` or `Ctrl+Scroll Up` |\n| Zoom out | `Ctrl+-` or `Ctrl+Scroll Down` |\n| Reset zoom | `Ctrl+0` |\n| Admin settings | `Ctrl+Alt+A` |\n| Force refresh | `F5` |\n\n---\n\n## 🧪 Running Tests\n\n```bash\ncd src/files\npytest tests/ -v\n\n# With coverage\npytest tests/ --cov=app --cov-report=term-missing\n\n# Single suite\npytest tests/test_stock_service.py -v\n```\n\nAll tests use an in-memory SQLite database with the full V12 schema applied — no file system side effects.\n\n---\n\n## 👨‍💼 Admin Panel Guide\n\nAccess: `Ctrl+Alt+A` · or the ⚙ icon in the header bar\n\n| Panel | Purpose |\n|---|---|\n| **Shop Settings** | Name, address, phone, email, currency, tax rate, admin PIN, language |\n| **Categories** | Create, edit, reorder inventory categories |\n| **Part Types** | Product type classifications with colour assignments |\n| **Models** | Device models and variants within categories |\n| **Scan Settings** | Scanner input delay, command barcode values, duplicate handling |\n| **Backup** | Manual backup trigger, retention-managed backup list |\n| **Import / Export** | CSV / JSON import and export per entity type |\n| **DB Tools** | VACUUM, integrity check, schema version display |\n| **Suppliers** | Supplier CRUD in admin context |\n| **Locations** | Warehouse bin / shelf location management |\n| **Customers** | Customer profile management |\n| **About** | App version, schema V23, DB size, OS info, update check |\n\n---\n\n## 📱 Barcode Workflow\n\n**Scanning:** Plug in any USB HID scanner → scan a product barcode → stock operation dispatches automatically via the Quick Scan tab.\n\n**Generation:** Select product → `Ctrl+B` → configure format and size → export PNG or print directly.\n\n**Command barcodes:** Print `CMD-TAKEOUT`, `CMD-INSERT`, and `CMD-CONFIRM` barcodes to control the Quick Scan workflow hands-free. Values are configurable in Admin → Scan Settings.\n\n---\n\n## 🔒 Data \u0026 Privacy\n\nAll data stays on your machine:\n\n```\n%LOCALAPPDATA%\\StockPro\\StockManagerPro\\stock_manager.db\n```\n\n- No internet connection required (update check is opt-in)\n- No telemetry, no user tracking; cloud sync is strictly opt-in (your own Turso database)\n- Complete audit log of every stock movement\n- Automatic backup every 5 minutes with configurable retention\n- SQLite WAL mode for crash safety\n\n**Logs:**\n```\n%LOCALAPPDATA%\\StockPro\\StockManagerPro\\logs\\\n```\n\n---\n\n## 🤝 Contributing\n\n```bash\ngit clone https://github.com/AbdullahBakir97/Stock-manager.git\ncd Stock-manager\ngit checkout dev\ngit checkout -b feature/your-feature-name\n\npython -m venv venv \u0026\u0026 venv\\Scripts\\activate\npip install -r requirements.txt\n\n# Run app\ncd src/files \u0026\u0026 python main.py\n\n# Run tests\npytest tests/ -v\n```\n\n**Layer rules (strictly enforced):**\n- UI never imports repositories directly — always go through services\n- Services never import UI — they return data or raise exceptions\n- Repositories contain only SQL and data mapping — no business logic\n- Models are pure dataclasses — no DB access, no side effects\n\n**Adding a new feature:**\n1. Model → `app/models/`\n2. Migration → `app/core/database.py` (V14+)\n3. Repository → `app/repositories/`\n4. Service → `app/services/`\n5. UI → `app/ui/pages/` or `app/ui/dialogs/`\n6. Translations → `app/core/i18n.py` (EN + DE + AR)\n7. Wire into `main_window.py` via the appropriate controller\n8. Tag + push → GitHub Actions builds, signs, and releases automatically\n\n---\n\n## 🐛 Troubleshooting\n\n**Application won't start**\nDelete `%LOCALAPPDATA%\\StockPro\\` to reset all data and config to defaults. Check that Windows Defender isn't blocking the executable.\n\n**Barcode scanner not recognised**\nVerify the scanner is in Keyboard Emulation (HID) mode. Test in Notepad first. Adjust input delay in Admin → Scan Settings.\n\n**Database errors**\nRun VACUUM and integrity check in Admin → DB Tools. Restore from a recent backup if needed (Admin → Backup).\n\n**Performance**\nThe async engine ensures the UI never blocks regardless of database size. If you see main-thread freezes please [open an issue](https://github.com/AbdullahBakir97/Stock-manager/issues) with your schema version and OS details.\n\n---\n\n## 📈 Releases\n\n**Current release: v2.6.4** · [Full changelog →](CHANGELOG.md)\n\nEvery release is built, signed, and published automatically by CI (`.github/workflows/release.yml`) on each `v*.*.*` tag — stamping the version across `version.py`, the installer files, this README, and `update_manifest.json`. The complete, per-version history lives in **[CHANGELOG.md](CHANGELOG.md)**.\n\n| Milestone | Highlights |\n|---|---|\n| **2.6.0** | Cloud-sync enable fix, dashboard stock-health accuracy, refreshed README + screenshots |\n| **2.5.x** | 📱 Phones (IMEI) module, optional cloud sync (Turso), 14 professional PDF reports, German-keyboard barcode round-trip fixes |\n| **2.3.x** | Zero-freeze async engine, controller refactor, full business suite (POS, Purchase Orders, Returns, Suppliers, Audit, Price Lists, Customers, Locations) |\n| **2.1 – 2.2** | Colour dimension in the matrix, barcode generator, Quick Scan workflow |\n| **1.0.0** | Core inventory, barcode scanning, multilingual interface, offline SQLite |\n\n---\n\n## 📄 License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\nCopyright © 2026 Abdullah Bakir\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[GitHub Repository](https://github.com/AbdullahBakir97/Stock-manager)** · **[Report a Bug](https://github.com/AbdullahBakir97/Stock-manager/issues)** · **[Request a Feature](https://github.com/AbdullahBakir97/Stock-manager/discussions)**\n\nHappy Inventory Managing 🚀\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabdullahbakir97%2Fstock-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabdullahbakir97%2Fstock-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabdullahbakir97%2Fstock-manager/lists"}