Skip to content

Architecture and roadmap

Jump to bottom
Joel B edited this page May 12, 2026 · 4 revisions

This page describes the structure of the Pynventory codebase and the project's current direction.

Project layout

pynventory/
├── pynventory/          # Python package containing the app code
│   ├── __init__.py
│   └── main.py          # entry point: terminal CLI loop
├── data/                # local runtime data (gitignored except .gitkeep)
│   ├── .gitkeep
│   └── products.db      # data/products.db, local SQLite database (not committed)
├── tests/               # test package (expanding)
├── .github/             # issue templates, PR template, workflows
├── README.md
├── requirements.txt     # Python dependencies
├── ruff.toml            # Ruff formatter/linter configuration
└── .gitignore

Key modules

  • pynventory/main.py - starts the terminal app, reads user commands, dispatches to the appropriate handler.
  • SQLite database - stores inventory data in data/products.db. Created automatically on first run.

Design notes

  • The app is a single-user terminal program. No authentication, no networking.
  • The database is local SQLite. Multi-user access is out of scope for current phases.

Current phase

The current focus is improving the CLI inventory app. Before building a web interface, the project should have a clearer inventory model and a safer contributor workflow.

Current priorities:

  • track product quantities
  • sell products and reduce stock
  • search products by name or brand
  • improve list output formatting
  • add simple automated tests
  • keep the contribution process beginner-friendly

Phase 1: Make the CLI inventory useful (in progress)

These are the next core features that make the inventory more practical.

  • Stock quantity tracking - add quantity to products so inventory levels can be tracked.
  • Search - find products by name or brand using partial, case-insensitive matches.
  • Sell products - reduce stock when products are sold.
  • Validate sell price - warn or block if sell price is lower than buy price.
  • Better formatted output - align columns and improve spacing when listing products.

Phase 2: Improve safety and contributor confidence

These make the project easier to work on without breaking existing behavior.

  • Simple tests - add basic automated tests for product creation, validation, and database operations.
  • Better error messages - tell the user clearly what went wrong and how to fix it.
  • Cleaner developer experience - keep files focused and easy to understand as the project grows.
  • Database reset guidance - document how to safely create or reset local development data.

Phase 3: Add useful inventory features

These features build on quantity tracking and make the app more realistic.

  • Inventory value report - show total stock value and total potential profit.
  • Filter by category - list only products in a chosen category.
  • Sort list - sort by brand, category, profit, price, or quantity.
  • Low-stock alerts - show products where quantity is below a chosen limit.
  • Export to CSV - export inventory data for use in spreadsheets.
  • Date added field - track when a product was first entered.
  • Last updated field - track when a product was last modified.

Phase 4: Larger future ideas

These should wait until the CLI behavior and data model are clearer.

  • Supplier info - add supplier details to products or a separate supplier table.
  • Restock history - log when stock increases.
  • Sales / stock movement history - log stock decreases and sales.
  • API layer - expose inventory functionality for a future front end.
  • Web version - build a browser-based interface using a framework chosen by the team.
  • Production environment - explore Docker or another deployment approach if the project grows.
  • Database upgrade - explore alternatives to SQLite if multi-user access becomes necessary.

Out of scope for now

These ideas are not rejected, but they should not be the immediate focus:

  • full web application
  • user accounts
  • authentication
  • production deployment
  • complex database migrations
  • advanced reporting

The project should grow step by step.

Suggesting roadmap changes

To suggest a roadmap change:

  1. Open a GitHub issue.
  2. Explain the idea.
  3. Explain why it would help the project.
  4. Add the right label.
  5. Link the issue to the project board.

Roadmap changes should be discussed before implementation starts. See the Contributor workflow page for how to propose work.

Clone this wiki locally