Skip to content
Janani-bnPublic

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Aisle Manager

Supermarket management and in-store navigation app with Seller and Buyer roles.

Sellers build their store layout and manage products. Buyers browse stores, build shopping lists, save recipes, and get a live optimized walking route through the store.


Tech Stack

Layer Technology
Backend FastAPI + SQLAlchemy + Alembic
Database PostgreSQL
Auth JWT (HS256), role-based (seller / buyer)
Frontend React 18 (Vite) + Tailwind CSS + react-konva
AI Google Gemini API (optional — AI shopping planner)

Prerequisites

Tool Version used Install
Python 3.11+ https://www.python.org/downloads/
Node.js 18+ https://nodejs.org/
PostgreSQL 14+ https://www.postgresql.org/download/

Verify everything is installed:

python3 --version
node --version
psql --version

First-Time Setup

1. Create the PostgreSQL database

psql -U postgres
CREATE DATABASE aisle_manager;
\q

Or use pgAdmin: right-click Databases → Create → Database, name it aisle_manager.


2. Backend setup

cd backend

Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate

Your prompt should show (venv).

Install dependencies:

pip install -r requirements.txt

Create the environment file:

cp .env.example .env

Open backend/.env and fill in your values:

DATABASE_URL=postgresql+psycopg2://postgres:YOUR_PASSWORD@localhost:5432/aisle_manager
SECRET_KEY=replace-with-a-random-string-at-least-32-characters
ACCESS_TOKEN_EXPIRE_MINUTES=10080
GEMINI_API_KEY=your_gemini_api_key_here

Generate a secure secret key:

python3 -c "import secrets; print(secrets.token_hex(32))"

GEMINI_API_KEY is optional. Without it, the AI Shopping Planner won't work but everything else does. Get a free key at https://aistudio.google.com/apikey.

Run database migrations (creates all tables):

alembic upgrade head

3. Frontend setup

Open a new terminal tab (keep the backend terminal open).

cd frontend
npm install

Running the App

You need two terminals running at the same time.

Terminal 1 — Backend:

cd backend
source venv/bin/activate
uvicorn app.main:app --reload --port 8000

Terminal 2 — Frontend:

cd frontend
npm run dev

Open http://localhost:5173 in your browser.

Service URL
App http://localhost:5173
API http://localhost:8000
API docs (Swagger) http://localhost:8000/docs

Creating Accounts

Go to http://localhost:5173 and click Create Premium Account.

  • Choose Seller to manage a store (products, layout, offers, analytics)
  • Choose Buyer to browse stores, build shopping lists, save recipes, and navigate in-store

There are no pre-seeded accounts — register your own.


Features

Seller

  • Create and manage a store
  • Add products with stock tracking
  • Drag-and-drop store layout editor (shelves, entrance, checkout)
  • Assign products to layout elements
  • Create offers (% off, fixed off, BOGO)
  • Sales analytics

Buyer

  • Browse stores and search products
  • Shopping lists with budget tracking
  • Save and manage recipes
  • AI Shopping Planner — describe what you want to cook and it auto-builds a list
  • Optimized in-store walking route with live rerouting
  • Accessibility-aware routing (avoid stairs, narrow aisles, restricted areas)
  • Shopping history with spend tracking and repeat-cart

Project Structure

aisle_manager/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry point + CORS
│   │   ├── database.py          # SQLAlchemy engine and session
│   │   ├── models/              # ORM models
│   │   ├── schemas/             # Pydantic request/response models
│   │   ├── routers/
│   │   │   ├── auth.py          # /register  /login  /me
│   │   │   ├── seller/          # store, products, offers, analytics, layout
│   │   │   └── buyer/           # stores, products, offers, lists, route, recipes, ai
│   │   ├── navigation/          # Dijkstra graph builder + TSP route optimizer
│   │   ├── core/                # config, JWT security, auth dependencies
│   │   └── utils/               # stock status helpers
│   ├── alembic/                 # migration scripts
│   ├── requirements.txt
│   ├── .env.example             # copy to .env and fill in
│   └── .env                     # your local config (never commit this)
│
└── frontend/
    └── src/
        ├── api/                 # Axios API clients
        ├── store/auth.js        # Zustand auth state
        ├── utils/navGraph.js    # client-side route computation
        └── pages/
            ├── auth/            # Login, Register
            ├── seller/          # Dashboard, Products, Offers, Analytics, Layout Editor
            └── buyer/           # Stores, Products, Lists, Route, Recipes, History

Environment Variables

All variables go in backend/.env:

Variable Required Description
DATABASE_URL Yes PostgreSQL connection string
SECRET_KEY Yes JWT signing secret — never commit this
ACCESS_TOKEN_EXPIRE_MINUTES No Token lifetime in minutes (default 10080 = 7 days)
GEMINI_API_KEY No Google Gemini key — enables AI Shopping Planner

Troubleshooting

psycopg2 install fails on macOS

brew install libpq
pip install -r requirements.txt

alembic upgrade head fails — "role does not exist" The username in DATABASE_URL doesn't match your PostgreSQL user. Check with psql -U postgres and update .env.

alembic upgrade head fails — "password authentication failed" Wrong password in DATABASE_URL. Update backend/.env to match your PostgreSQL password.

"relation does not exist" at runtime Migrations didn't complete. Run alembic upgrade head again with the venv active.

Permission denied when running npm run dev

chmod +x frontend/node_modules/.bin/*

Frontend shows blank page or CORS errors Make sure the backend is running on port 8000 before opening the frontend.

Port already in use

# kill whatever is on port 8000
lsof -ti:8000 | xargs kill -9

# kill whatever is on port 5173
lsof -ti:5173 | xargs kill -9

AI Planner returns an error Add GEMINI_API_KEY=your_key to backend/.env and restart the backend.

Route page shows "no mapped location" The seller must open the Layout Editor, place products on the store map, and publish the layout before buyers can use routing.


Resetting the Database

To wipe all data and start fresh (keeps table structure):

cd backend
source venv/bin/activate
python3 -c "
from app.database import SessionLocal
from sqlalchemy import text
db = SessionLocal()
for t in ['shopping_list_shares','shopping_list_items','shopping_history',
          'shopping_lists','recipes','product_locations','layout_elements',
          'shop_layouts','offers','products','categories','aisles',
          'notifications','stores','users']:
    db.execute(text(f'DELETE FROM {t}'))
db.commit()
db.close()
print('Done.')
"

To wipe everything and recreate tables from scratch:

alembic downgrade base
alembic upgrade head

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages