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.
| 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) |
| 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 --versionpsql -U postgresCREATE DATABASE aisle_manager;
\qOr use pgAdmin: right-click Databases → Create → Database, name it aisle_manager.
cd backendCreate and activate a virtual environment:
python3 -m venv venv
source venv/bin/activateYour prompt should show (venv).
Install dependencies:
pip install -r requirements.txtCreate the environment file:
cp .env.example .envOpen 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_hereGenerate a secure secret key:
python3 -c "import secrets; print(secrets.token_hex(32))"
GEMINI_API_KEYis 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 headOpen a new terminal tab (keep the backend terminal open).
cd frontend
npm installYou need two terminals running at the same time.
Terminal 1 — Backend:
cd backend
source venv/bin/activate
uvicorn app.main:app --reload --port 8000Terminal 2 — Frontend:
cd frontend
npm run devOpen http://localhost:5173 in your browser.
| Service | URL |
|---|---|
| App | http://localhost:5173 |
| API | http://localhost:8000 |
| API docs (Swagger) | http://localhost:8000/docs |
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.
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
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
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 |
psycopg2 install fails on macOS
brew install libpq
pip install -r requirements.txtalembic 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 -9AI 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.
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