ASTU Inventory

A web-based store and laboratory administration platform for Adama Science and Technology University, College of Electrical Engineering and Computing.

It tracks what the college owns — products, stock items, stores, labs, shelves and tables — and manages the people and requests around them: departments, staff roles, and the full borrow request lifecycle.

---

Features

• Inventory management — products organised by category/sub-category with custom specifications and measurement units, plus individual stock items with dead stock numbers, suppliers, purchase years and expiration dates.

• Physical locations — stores (with shelves, rows and columns) and labs (with tables), each scoped to a department and tracked by block and room.

• Borrow workflow — staff submit borrow requests, store officers approve or reject them with a reason, and every action is kept in a borrow history.

• Role-based access — five roles, created automatically after migration, each with its own permission set:

  Role	Responsibility
  College Dean	Manages departments across the college
  Department Head	Manages staff members of a department
  Store Officer	Manages department stores and borrow requests
  Lab Assistant	Manages lab items
  Staff Member	Borrows items

• Low-stock awareness — every product carries a critical number and a live available count.

• Reporting — export data to Excel via pandas, XlsxWriter and openpyxl.

• Contextual help — per-view help pages, generated from the URL configuration and editable with a rich-text editor.

• Internationalisation — all user-facing strings are translatable; language and timezone are configurable.

Tech stack

Framework	Django 3.2 (LTS)
Language	Python 3.7 – 3.9
Database	PostgreSQL (SQLite by default for local work)
Server	Gunicorn
Monitoring	Sentry
Key packages	django-widget-tweaks, django-smart-selects, django-summernote, pandas, Pillow

Project layout

astu_inventory/
├── apps/
│   ├── auser/       Custom user model, departments, roles, staff management
│   ├── core/        Dashboard, borrow requests and history
│   ├── inventory/   Stores, labs, shelves, tables, products, items, specifications
│   └── help/        Per-view help pages
├── settings/        base · local · production · tests
├── static/
├── templates/
└── urls.py
requirements/        base · local · production · tests

Getting started

Prerequisites

• Python 3.7 – 3.9
• PostgreSQL (optional locally — SQLite is used when DATABASE_URL is unset)

Installation

git clone https://github.com/rebunitech/astu-store.git
cd astu-store

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements/local.txt

Configuration

Settings are read from the environment (via python-decouple), so create a .env file in the project root:

SECRET_KEY=replace-me
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost
DATABASE_URL=postgres://user:password@127.0.0.1:5432/astu_inventory
LANGUAGE_CODE=en-us
TIME_ZONE=UTC
ASTU_INVENTORY_ENVIRONMENT=local

Production additionally requires SERVER_EMAIL, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, EMAIL_PORT and — if you use error tracking — SENTRY_DSN.

Running

export DJANGO_SETTINGS_MODULE=astu_inventory.settings.local

python manage.py migrate            # also creates the five roles
python manage.py createsuperuser
python manage.py generatehelp       # seed help pages for every view
python manage.py runserver

The app is available at http://127.0.0.1:8000/ and redirects to the dashboard; the Django admin lives at /admin/.

In local development, outgoing email is written to the emails/ directory instead of being sent, and the Django Debug Toolbar is enabled at /__debug__/.

Testing

python manage.py test --settings=astu_inventory.settings.tests

coverage run manage.py test --settings=astu_inventory.settings.tests
coverage report

tox                                 # full matrix

The test settings disable migrations and use a fast password hasher, so the suite runs quickly.

Code style

The project uses black (line length 119), isort, flake8 and bandit, all wired into pre-commit:

pre-commit install
pre-commit run --all-files

Both linting and tests run on every push and pull request through GitHub Actions.

Commit messages

Commits follow the template in .git-commit-template — a tag, then an imperative subject of at most 72 characters:

[feat] Add pagination to lab assistant list

Available tags: feat, fix, refactor, style, doc, test, version. Enable the template once per clone:

git config commit.template .git-commit-template

Deployment

Install production dependencies, point DJANGO_SETTINGS_MODULE at the production settings, collect static files and serve with Gunicorn:

pip install -r requirements/production.txt
export DJANGO_SETTINGS_MODULE=astu_inventory.settings.production

python manage.py migrate
python manage.py collectstatic --noinput
gunicorn astu_inventory.wsgi:application

Static files are collected to ../../asset and uploads are stored in ../../uploads, relative to the astu_inventory package — serve both from your web server.

Note: the HTTPS-related security settings in settings/production.py (SECURE_SSL_REDIRECT, SESSION_COOKIE_SECURE, CSRF_COOKIE_SECURE) are currently disabled. Turn them on when deploying behind TLS.

License

Released under the GNU General Public License v3.0.