Project StockRoom 📦

A comprehensive, crash-proof inventory management system for organizing and tracking products and stockroom locations.

Overview

Project StockRoom is a professional-grade CLI (Command Line Interface) application designed to streamline inventory management in retail or warehouse environments. It provides a robust, user-friendly system for tracking products, managing stockroom locations, and maintaining accurate inventory counts.

Key Strengths

• 🛡️ Crash-Proof - Comprehensive error handling and validation
• 🎯 Modular Architecture - Clean separation of concerns
• 📦 Well-Tested - 147 tests in the suite (see Testing for current status)
• 💾 Persistent Storage - CSV-based data persistence
• 🎨 User-Friendly - Colorized terminal output with intuitive menus
• 🚀 Scalable - Easy to extend and maintain
• 🐍 Zero Runtime Dependencies - Uses only the Python standard library (csv, os, pathlib)

Features

Product Management

• ✅ Add Products - Create new products with category assignment and initial count
• ✅ Edit Products - Modify product names and inventory counts
• ✅ Delete Products - Remove products from inventory
• ✅ Search Products - Find products by name or product number
• ✅ Sort Inventory - Organize products by product number

Category Management

• ✅ Create Categories - Define product categories with auto-generated codes
• ✅ Add Categories - Expand category list with duplicate prevention
• ✅ Set Categories - Configure complete category structure
• ✅ View Categories - Display all defined categories
• ✅ Category Products - List all products in a specific category

Location Management

• ✅ Create Locations - Add single or multiple stockroom locations
• ✅ Location Naming - Hierarchical naming (Category-Aisle-Column-Row)
• ✅ Backstock Products - Move products from salesfloor to backstock locations
• ✅ Take Stock - Remove products from locations
• ✅ Audit Locations - View all products in a location

Data Management

• ✅ CSV Import - Load inventory from CSV files
• ✅ CSV Export - Save inventory to CSV files
• ✅ Data Persistence - Automatic save/load functionality
• ✅ Error Recovery - Graceful handling of corrupted data

Project Structure

Project_StockRoom/
├── README.md                        ← You are here
├── Stockroom_App_UML.pdf           ← Architecture diagram
│
├── venv/                            ← Virtual environment
│   ├── Main.py                      ← Application entry point
│   ├── Product.py                   ← Product class
│   ├── MasterInventory.py          ← Inventory state & core helpers (+ re-exports)
│   ├── CategoryManager.py          ← Category state helpers & menus
│   ├── InventoryIO.py              ← Master/unlocated CSV persistence
│   ├── InventoryUI.py              ← Interactive inventory console menus
│   ├── InputUtils.py               ← Shared cancel-aware input helper
│   ├── MasterStockRoom.py          ← Location management
│   ├── ProductLocation.py          ← Location tracking
│   ├── Colorize.py                 ← Terminal colors
│   ├── Messages.py                 ← User messages & input
│   ├── config.py                   ← Central data-file path configuration
│   │
│   ├── data/                        ← All CSV data lives here
│   │   ├── master_inventory.csv    ← Product data
│   │   ├── master_stockroom_location.csv ← Category data
│   │   ├── unlocated_inventory.csv ← Received-but-unlocated product pool
│   │   └── StockroomLocations/     ← Location files (by category)
│   │       ├── 01-01-A-01.csv
│   │       ├── 01-01-A-02.csv
│   │       └── ... (organized by category)
│   │
│   ├── FILES_CREATED.txt           ← Notes on generated files
│   │
│   └── Tests/                      ← Comprehensive test suite
│       ├── conftest.py
│       ├── pytest.ini
│       ├── test_product.py
│       ├── test_colorize.py
│       ├── test_messages.py
│       ├── test_master_inventory.py
│       ├── test_master_stockroom.py
│       ├── test_product_location.py
│       ├── test_integration.py
│       └── (6 documentation files)

Requirements

• Python 3.12+
• pip (only needed to install the test dependencies)
• Runtime dependencies: none — the application uses only the Python standard library.
• Test dependencies: pytest (>= 7.0), pytest-cov (optional, for coverage).

Note on venv/: In this repository the application source code lives inside the venv/ directory (the folder was reused as the project root for the source). It is not a standard throwaway virtual environment. Do not delete it.

TODO: Add a requirements.txt (or pyproject.toml) pinning the test dependencies so setup can be automated.

Installation

1. Clone or navigate to the project

   cd Project_StockRoom

2. (Optional) Create and activate a virtual environment for the tools

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

3. Install test dependencies (only required to run the test suite)

   pip install pytest pytest-cov

4. Run the application

   cd venv
   python3 Main.py

Environment Variables

The application does not read any environment variables. All data-file paths are defined in config.py and resolved relative to the current working directory. Every CSV file lives under a single data/ directory:

• data/master_inventory.csv
• data/master_stockroom_location.csv
• data/unlocated_inventory.csv
• data/StockroomLocations/*.csv

The data/ directory (and its StockroomLocations/ subfolder) is created automatically on first save if missing.

TODO: If configurable data paths are desired in the future, document the corresponding environment variables here.

Usage

Running the Application

Run from inside the venv/ directory so the module imports and CSV paths resolve correctly:

cd venv
python3 Main.py

On startup the app loads data/master_stockroom_location.csv, data/master_inventory.csv, and data/unlocated_inventory.csv (missing files are handled gracefully).

Main Commands

Commands are case-insensitive. The list below reflects the current venv/Main.py router.

Everyday Commands

MENU                Display the main command list
ADMIN               Show advanced/administration commands
SEARCH <term>       Search Master Inventory by name (prompts if no term given)
# SEARCH            Search Master Inventory by product number
CAT PROD            Show products in a category

Stock Commands

BACKSTOCK [number]  Move a product into a backstock location (interactive if no number)
TAKE                Take a product from backstock to the salesfloor
RECEIVE             Receive product into the unlocated pool
UNLOCATED           Show unlocated product and place/backstock it
AUDIT               Show all products in a location

App Commands

SAVE                Save Master Inventory, stockroom, and unlocated CSVs
QUIT                Save (if unsaved changes) and exit the application

Admin Commands (via ADMIN)

ADD                 Add a new product
EDIT                Edit an existing product
DELETE PRODUCT      Delete a product
ADD CAT             Add a new category
SET CAT             Set all categories (WARNING: overwrites ALL categories)
SHOW CAT            Display all categories
CREATE LOC          Create a single stockroom location
CREATE MULTI LOC    Create multiple locations at once
READ LOC            Import Master Stockroom CSV
READ                Import Master Inventory CSV
WRITE               Write Master Inventory to CSV
SORT                Sort/write Master Inventory by product number

Cancelling an Operation

X / CANCEL / BACK   Cancel the current interactive command

Example Workflow

1. Start the app

   python3 Main.py

2. Create categories

   Command: ADD CAT
   Category: ELECTRONICS
   Category: FURNITURE
   Category: (type DONE)
   

3. Add products

   Command: ADD
   Select category: 1 (ELECTRONICS)
   Product name: LAPTOP
   Initial count: 25
   

4. Backstock products

   Command: BACKSTOCK 0101
   Amount: 10
   Select location: Create new or select existing
   

5. Save changes

   Command: SAVE
   

Testing

Quick Start

cd venv/Tests
python3 -m pytest -v

Test Suite Overview

• 147 Total Tests in the suite
• Last run: 141 passing, 3 skipped, and 3 failing in test_master_stockroom.py::TestComputeNextLocation (location roll-over edge cases: row/column/aisle at limit).

TODO: The 3 failing compute_next_location tests indicate the roll-over logic and/or the tests are out of sync. Reconcile the expected behavior and fix so the suite is fully green.

Running Specific Tests

# Run all tests
python3 -m pytest -v

# Run specific test file
python3 -m pytest test_product.py -v

# Run tests matching pattern
python3 -m pytest -k "inventory" -v

# Generate coverage report
python3 -m pytest --cov=.. --cov-report=html

Test Categories

• Unit Tests - Individual module testing (test_product.py, test_master_inventory.py, etc.)
• Integration Tests - End-to-end workflows (test_integration.py)
• Skipped Tests (3) - Complex interactive scenarios

Documentation

For detailed testing information, see:

• Tests/RUN_TESTS.md - How to run tests
• Tests/TEST_SUITE_README.md - Complete test documentation
• Tests/QUICK_START.md - Quick reference

Architecture

Module Design

┌─────────────────────────────────────────────────────────────┐
│                        Main.py                              │
│                  (CLI Interface & Router)                   │
└─────────────────────────────────────────────────────────────┘
           ↓                     ↓                    ↓
    ┌──────────────┐  ┌──────────────────┐  ┌─────────────────┐
    │ MasterInv.   │  │ MasterStockRoom  │  │ ProductLocation │
    │ (Inventory)  │  │ (Locations)      │  │ (Locations I/O) │
    └──────────────┘  └──────────────────┘  └─────────────────┘
           ↓                     ↓                    ↓
    ┌──────────────┐  ┌──────────────────┐  ┌─────────────────┐
    │  Product.py  │  │  (Location Mgmt) │  │ (File I/O)      │
    │ (Data Model) │  │                  │  │                 │
    └──────────────┘  └──────────────────┘  └─────────────────┘
           
    ┌──────────────────────────────────────────────────────────┐
    │  Colorize.py & Messages.py (UI & User I/O)             │
    │  ├─ Text colorization                                   │
    │  ├─ Message generation                                  │
    │  └─ Input validation & retry logic                      │
    └──────────────────────────────────────────────────────────┘
           
    ┌──────────────────────────────────────────────────────────┐
    │  CSV Files (Data Persistence, under data/)              │
    │  ├─ data/master_inventory.csv                          │
    │  ├─ data/master_stockroom_location.csv                 │
    │  └─ data/StockroomLocations/*.csv                      │
    └──────────────────────────────────────────────────────────┘

Key Components

1. Product.py - Product data model with normalization
2. MasterInventory.py - Inventory state (single source of truth) & core helpers; re-exports the modules below for backward compatibility
3. CategoryManager.py - Category lookup/creation helpers & menus
4. InventoryIO.py - Master & unlocated inventory CSV persistence
5. InventoryUI.py - Interactive inventory console menus (search, edit, receive, etc.)
6. InputUtils.py - Shared cancel-aware user_input helper
7. MasterStockRoom.py - Location creation & management
8. ProductLocation.py - Location-level inventory tracking
9. Colorize.py - Terminal color formatting
10. Messages.py - User prompts & input validation
11. Main.py - CLI router & application loop

CSV File Format

data/master_inventory.csv

Product #,Product Name,On Hand Count
0101,ELECTRONICS,25
0102,LAPTOP STAND,15
0201,DESK,10

data/master_stockroom_location.csv

Category,Code
ELECTRONICS,01
FURNITURE,02
TOOLS,03

data/StockroomLocations/01-01-A-01.csv

Product #,Product Name,Amount
0101,ELECTRONICS,10
0102,LAPTOP STAND,5

Data Model

Product Structure

{
    "product_num": "0101",      # 4-digit code (zero-padded)
    "product_name": "ELECTRONICS",  # Uppercase
    "on_hand_count": 25         # Integer quantity
}

Location Naming Convention

CATEGORY-AISLE-COLUMN-ROW
Example: 01-02-A-03
    01 = Category code
    02 = Aisle number (01-20)
    A  = Column letter (A-J)
    03 = Row number (01-20)

Error Handling

The application implements comprehensive error handling:

• ✅ Input Validation - All user inputs checked and normalized
• ✅ File I/O Protection - Graceful handling of missing/corrupted files
• ✅ Data Validation - CSV parsing with error recovery
• ✅ State Management - Consistent state across operations
• ✅ User Feedback - Clear error messages and recovery options

Performance

• Startup Time - < 1 second
• Search Time - < 100ms for typical inventories
• CSV Load - < 500ms for 10,000+ items
• Memory Usage - ~50MB for 10,000 products

Documentation

In-Project Documentation

• README.md - This file (project overview)
• Stockroom_App_UML.pdf - Architecture diagram
• Tests/RUN_TESTS.md - Testing guide
• Tests/QUICK_START.md - Quick reference
• Tests/TEST_SUITE_README.md - Complete test docs

Code Documentation

• Inline comments for complex logic
• Docstrings for public functions
• Type hints where applicable

Development

Adding New Features

1. Update relevant module (e.g., MasterInventory.py)
2. Add unit tests in Tests/ folder
3. Update documentation
4. Run full test suite to verify

Running Tests

cd Tests
python3 -m pytest                    # Run all tests
python3 -m pytest -v                 # Verbose
python3 -m pytest --cov=..           # With coverage

Code Style

• Language - Python 3.12+
• Formatting - Clean, readable code
• Naming - Descriptive variable and function names
• Comments - For non-obvious logic only

Troubleshooting

Issue: Tests fail to run

Solution: Ensure you're in the Tests directory:

cd venv/Tests
python3 -m pytest

Issue: "File not found" errors

Solution: Run from the venv directory and ensure CSV files exist

Issue: Module import errors

Solution: Ensure you're running from the correct directory with proper Python path

Issue: Data not saving

Solution: Check file permissions and ensure StockroomLocations directory exists

Contributing

Guidelines

1. Write tests for new code
2. Follow existing code style
3. Update documentation
4. Ensure all tests pass
5. Add meaningful commit messages

Testing Requirements

• All new features must have tests
• Minimum 80% code coverage
• All tests must pass before committing

License

TODO: No LICENSE file is present in the repository. Add one to declare the project's license. The prior README referenced an MIT badge, but no license file backs that claim. Until a LICENSE file is added, the project is provided as-is for educational and business use, with all rights reserved by the author (Aaron Grincewicz).

Support & Contact

For issues, questions, or suggestions:

1. Check the documentation files
2. Review test files for usage examples
3. Examine the UML diagram for architecture

Changelog

Version 1.0 (Current)

• ✅ Full inventory management
• ✅ Location-based tracking (incl. unlocated/received pool)
• ✅ CSV data persistence
• ✅ 147-test suite
• ✅ Error handling on load/save
• ✅ Colorized terminal UI

---

Last Updated: July 10, 2026
Author: Aaron Grincewicz
Tests: 141 passing / 3 skipped / 3 failing (see Testing)