BillMate

A beginner-friendly, lightweight Flask app to generate shopping bills with simple smart discounts. Uses SQLite for storage, plain HTML/CSS for the UI, and Python for backend logic.

Features

• Enter up to 5 items (name, quantity, price)
• Automatic discounts:
  • 2% per-item discount if quantity >= 10
  • 10% cart discount if subtotal after item discounts > 1000
  • Extra 5% cart discount if 5 or more distinct items
• View the generated bill and recent bill history

Tech Stack

• Backend: Python (Flask)
• Frontend: HTML, CSS
• Database: SQLite (file billmate/billmate.db auto-created)

Quick start (from project root)

# 1) (Recommended) create and activate a virtual environment
python3 -m venv .venv && source .venv/bin/activate   # macOS/Linux
# or on Windows PowerShell:
# py -m venv .venv; .venv\Scripts\Activate.ps1

# 2) Install dependencies
pip install -r requirements.txt

# 3) Run the app
python billmate/app.py

# Alternatively, use the helper scripts from project root:
./run.sh     # macOS/Linux
run.bat      # Windows

Setup

1. Create and activate a virtual environment (recommended)
   • macOS/Linux

     python3 -m venv .venv
     source .venv/bin/activate

   • Windows (PowerShell)

     py -m venv .venv
     .venv\\Scripts\\Activate.ps1

2. Install dependencies

   pip install -r requirements.txt

3. Create your environment file (optional but recommended)

   cp .env.example .env
   # then edit .env to adjust SECRET_KEY / HOST / PORT / DEBUG

4. Run the app

   # Option A: from root
   python billmate/app.py
   
   # Option B: helper scripts from root
   ./run.sh     # macOS/Linux
   run.bat      # Windows

5. Open your browser at http://127.0.0.1:5000 (or your HOST:PORT if changed)

Project Structure

billmate/
  app.py
  billmate.db (auto-created)
  requirements.txt
  templates/
    base.html
    index.html
    bill.html
    history.html
  static/
    styles.css

Notes

• The code uses straightforward SQLite statements without an ORM to remain easy to follow.
• If you want to reset data, delete the billmate.db file (with the app stopped).
• For production use, you would want more robust validation, authentication, and deployment setup.

Run and Debug in VS Code

You can run directly, or set up a one-click debug configuration.

• Manual run via VS Code Terminal:

  • Open the folder in VS Code.
  • Select your virtual environment as the Python interpreter.
  • Terminal > New Terminal, then:

    source .venv/bin/activate   # macOS/Linux
    # or: .venv\\Scripts\\Activate.ps1  # Windows PowerShell
    python billmate/app.py

• One-click launch (optional): create .vscode/launch.json with:

  {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "BillMate (Launch)",
        "type": "python",
        "request": "launch",
        "program": "${workspaceFolder}/billmate/app.py",
        "console": "integratedTerminal",
        "envFile": "${workspaceFolder}/.env"
      }
    ]
  }

Then press F5 to start the app with variables from .env.

Environment variables

Configure via .env (loaded by python-dotenv). Defaults are safe for local use.

• SECRET_KEY — Flask session key (use a strong secret in non-dev).
• HOST — default 127.0.0.1.
• PORT — default 5000.
• DEBUG — true/false (default true).

Compatibility

• Requires Python 3.8+ (Flask 3.x requirement).
• Works on macOS, Windows, and Linux.
• Uses SQLite; the database file is created at billmate/billmate.db automatically.

Troubleshooting

• Port already in use: change PORT in .env, or stop the other process.
• Env not loading: ensure python-dotenv is installed and .env is at the project root.
• DB locked errors: stop the app and retry; SQLite allows a single writer.