Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/InnoDev69/StockManager/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through getting StockManager running on your local machine, logging in with the default root account, adding your first product to the inventory, and recording a sale — all using the development server. By the end you’ll have a working instance and a clear picture of how the REST API maps to the UI workflows. For production setup, building the desktop executable, or configuring email notifications, see the Installation guide.
1

Clone the repository and install dependencies

Clone the StockManager repository and install its Python dependencies. The project requires Python 3.10 or newer.
git clone https://github.com/InnoDev69/StockManager.git
cd StockManager
pip install -r requirements.txt
The requirements.txt pins Flask 3.0, Waitress 2.1, PyWebView 6.1, Pillow, ReportLab, and python-barcode, among others. A virtual environment is strongly recommended to avoid conflicts with other Python projects on your machine.
python -m venv .venv
source .venv/bin/activate      # Linux / macOS
.venv\Scripts\activate         # Windows
pip install -r requirements.txt
2

Create the .env file

StockManager reads configuration from a .env file in the project root. At minimum you need a secret key for Flask session signing.
# .env
FLASK_SECRET_KEY=change-me-to-a-long-random-string
Generate a strong value with Python:
python -c "import secrets; print(secrets.token_hex(32))"
Copy the output and paste it as the value of FLASK_SECRET_KEY. Without this variable the app falls back to the insecure default "a", which is fine for a first test but must not be used beyond that.
3

Start the development server

Run the dev server using run-dev.py. This calls app.run(host="127.0.0.1", port=5000, debug=True), which starts Flask’s built-in Werkzeug server with debug mode on. Debug mode enables the automatic reloader (the server restarts when you edit a Python file) and shows full tracebacks in the browser on errors.
python run-dev.py
Expected output:
 * Running on http://127.0.0.1:5000
 * Debug mode: on
The SQLite database is created automatically at ./data/stock.db on this first launch. The init_db() routine creates all tables, applies any pending migrations, and inserts the default root user if none exists.
run-dev.py uses Flask’s built-in development server. Do not use this mode for the desktop app experience or for production deployments. Use python main.py for the PyWebView desktop window instead (see Installation).
4

Log in with the root account

Open http://127.0.0.1:5000 in your browser. You’ll be redirected to the login page. Sign in with the auto-created credentials:
  • Username: root
  • Password: root1234
You can also authenticate via the API directly. The login endpoint returns a session cookie that all subsequent API calls must include:
curl -c cookies.txt -X POST http://127.0.0.1:5000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "root", "password": "root1234"}'
A successful response:
{
  "success": true,
  "user_id": 1,
  "username": "root",
  "role": "root"
}
Change the root password immediately after your first login. The default credentials (root / root1234) are public knowledge and must not remain in place on any persistent installation.
5

Create your first product

Products can be created through the Inventory section of the UI (navigate to the sidebar after logging in) or via the REST API. Only users with the admin or root role can create products.
curl -b cookies.txt -X POST http://127.0.0.1:5000/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "1234567890",
    "name": "Café Molido",
    "quantity": 100,
    "min_quantity": 10,
    "price": 5.99,
    "description": "Café molido premium"
  }'
A successful response:
{
  "message": "Producto creado exitosamente"
}
The product is now visible in the inventory table. Because the initial quantity (100) is above the minimum threshold (10), no low-stock notification is triggered. A notification of type success is still created for the acting user confirming the product was added.Required fields: barcode, name, quantity, min_quantity, price
Optional fields: description, expiration_date
6

Register a sale

Use POST /api/sales/bulk to record a sale. The endpoint accepts one or more items in a single transaction, deducts stock automatically, and generates a sale record with full line-item detail. Any authenticated user (vendor, admin, or root) can register sales.First, retrieve the product ID if you don’t already know it:
curl -b cookies.txt "http://127.0.0.1:5000/api/items?q=Caf%C3%A9"
Then register the sale using the product’s numeric ID:
curl -b cookies.txt -X POST http://127.0.0.1:5000/api/sales/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"item_id": 1, "quantity": 2}
    ],
    "payment_method": "Efectivo"
  }'
A successful response:
{
  "ok": true,
  "sale_id": 1,
  "items": [
    {
      "item_id": 1,
      "name": "Café Molido",
      "quantity": 2,
      "unit_price": 5.99,
      "subtotal": 11.98
    }
  ],
  "total": 11.98
}
The payment_method field is a free-form string — common values used in the application are "Efectivo" (cash), "Tarjeta" (card), and "Transferencia" (bank transfer). After the sale, the product’s stock is decremented from 100 to 98, and a low-stock check runs to see if any product has dropped below its minimum threshold.
This quickstart uses the development server (python run-dev.py) which is ideal for exploring the API and testing workflows. When you’re ready to deploy the full desktop application with the PyWebView window, configure environment variables, or set up email notifications for password resets, head to the Installation guide for complete coverage.

Build docs developers (and LLMs) love

Get started for freeTalk to us