Overview

Shop312 lets users discover locally owned businesses and community events. The web app consists of a main page with a map and search bar where users can search for products. The results show locally owned shops on the map that sell those products. Each shop has its own detailed page displaying inventory, contact information, business hours, and upcoming events.

Features

• Interactive Map: Main page displays all shops on a Leaflet-powered map
• Product Search: Search bar finds shops that sell specific products
• Shop Details: Individual shop pages with inventory, hours, contact info, and location
• Events Calendar: Browse upcoming community events by date
• Event Management: Individual event pages with detailed information and venue links
• Shop Events Integration: Shop pages display upcoming events (next 60 days)
• Admin Interface: Django admin for managing shops, products, inventory, and events
• Responsive Design: Bootstrap-styled UI that works on mobile and desktop
• Import data: Use the custom django admin tool load_supplies to import data from a spreadsheet, see supplies.csv as an example. Run with python manage.py load_supplies supply-list.csv
• Shop owner accounts. Account system for shop owners. Shop owners can create and edit Shop objects.

TODO

• [HIGH; NEED] Fine-tune the thresholds for multi-entity search
• [HIGH; NEED] Accessibility features
• [HIGH; NEED] Selective user registration; users either have to provide a code on signup or their signup has to be approved, or maybe something else? This prevents arbitrary accounts owned by non-business owners or business impersonations
• [HIGH; NEED] Data ingestion module to easily import shop inventories based on crude data formats (google spreadsheet etc).
  • For existing products, this tool would have to be able to map the product from the spreadsheet to an existing product
  • For products that don't exist, the tool would create new product records in the products table. This could be a human-enforced operation, where the tool suggests new product and the user confirms whether to add it or instead identify which product should be mapped to the spreadsheet item
  • It's worth noting that businesses using Square and Toast can easily export a csv of their inventory. Clover might only export to excel
• [LOW; NEED] Calendar input widget for creating/editing events form is stuck on dark theme when light mode is enabled.
• [LOW; OPTIONAL] Include SKU for common products
• [LOW; OPTIONAL] Use a public SKU database to fetch information for products with a SKU (image)
• [LOW; OPTIONAL] Update icons. Not just an original set (that would be very nice), but some of the icons don't really fit the category name (see tattoos & piercings)
• [VERY LOW; OPTIONAL] Chicago chatroom? Using matrix.org COMPLETED [HIGH; NEED] Set up osm tile server and use it. Currently WIP
• COMPLETED [MED; NEED] Guides ("A weekend in Andersonville" etc etc) in place of reviews. Curated by locals
• COMPLETED Add event creation form for shop owners
• COMPLETED Add accounts for shop owners
• COMPLETED Add images for products and shops
• COMPLETED Add events table
• COMPLETED [HIGH; NEED] Fix "Furniture & Home Décor" shop category url gets rendered differently and the page doesn't load properly
• COMPLETED [HIGH; NEED] Multi-entity search; users should be able to search not just items but shops and events.

Project Structure

Models (shops/models.py:4-86)

• Shop: Stores shop information including name, owner, address, coordinates, contact info, and business hours
• ShopCategory: Shop category with reference to icon for display.
• Product: Contains product details like name, description, and category
• Inventory: Links shops to products with pricing and stock information
• Event: Community events with title, description, date/time, location, and optional shop association
• User: Django's out of the box User auth model, for shop owners.

Views (shops/views.py:8-88)

• index: Main page showing map and all shops
• shop_detail: Individual shop pages with inventory, location, and upcoming events
• search: Product search functionality that finds shops selling matching products
• events_calendar: Events calendar page showing upcoming events grouped by date
• event_detail: Individual event pages with full details and venue information

Templates

• Interactive map using Leaflet for location visualization
• Bootstrap-styled responsive design
• Search functionality integrated with map display
• Shop detail pages showing inventory, hours, contact info, and upcoming events
• Events calendar with day-by-day event breakdown
• Individual event detail pages with venue integration

Getting Started

Prerequisites

This project uses uv for dependency management. Make sure you have uv installed.

Setup

1. Create a superuser (for admin access):

   uv run python manage.py createsuperuser
   

2. Run the development server:

   uv run python manage.py runserver
   

3. Access the application:

   • Main website: http://127.0.0.1:8000/
   • Admin interface: http://127.0.0.1:8000/admin/

Adding Data

1. Visit the admin interface at /admin/ and log in with your superuser credentials
2. Add shops with their location coordinates, contact info, and business hours
3. Create products with names, descriptions, and categories
4. Link products to shops through the Inventory model with pricing and stock information
5. Create events with dates, times, locations, and optional shop associations

Usage

• Browse Shops: The main page shows all shops on an interactive map
• Search Products: Use the search bar to find shops selling specific products
• View Shop Details: Click on any shop to see its inventory, hours, contact information, and upcoming events
• Browse Events: Visit the Events page to see all upcoming community events organized by date
• Event Details: Click on any event to see full details, venue information, and links to associated shops
• Map Navigation: Click map markers to see shop information and navigation links

Technology Stack

• Backend: Django 6.0
• Frontend: Bootstrap 5.3, Leaflet.js
• Database: SQLite (default)
• Package Management: uv

Database Models

Shop

• Basic info: name, address, phone, email, website
• Location: latitude, longitude
• Business hours for each day of the week
• Timestamps: created_at, updated_at

Product

• name, description, category
• Timestamps: created_at, updated_at

Inventory

• Links Shop and Product (many-to-many through model)
• price, stock_quantity, in_stock status
• Timestamps: created_at, updated_at