Project Overview

This is a Mini Flask E-Commerce application - a simple educational demo for classroom use. It's a complete e-commerce system with customer and staff functionality, using Flask + SQLite with intentionally simplified security (plaintext passwords) for teaching purposes.

Key Features:

• Product catalog with search
• Guest and registered user checkout
• User account management
• Shopping cart functionality
• Staff order fulfillment portal
• Order status progression (Open → Ready → Shipped → Picked-up)

Architecture

Backend: Flask web application with SQLite database Frontend: Jinja2 templates with Bootstrap 5 styling
Database: SQLite with schema auto-initialization Session Management: Flask sessions for cart and user state

Core Components

• app.py - Main Flask application with all routes and business logic
• schema.py - Database schema definition and sample data seeding
• templates/ - Jinja2 HTML templates using Bootstrap
• ecommerce.db - SQLite database (auto-created on first run)

Database Schema

• users - Customer/staff accounts (plaintext passwords for demo)
• products - Product catalog with name, description, price, stock
• orders - Customer orders (supports both guest and registered users)
• order_items - Line items for each order

Key Routes Architecture

• / - Product listing with search
• /signup, /login, /logout - Authentication
• /account - User profile management
• /cart, /add_to_cart/<pid>, /remove_from_cart/<pid> - Shopping cart
• /checkout - Order placement (guest or logged-in)
• /fulfill - Staff portal for order management
• /my_orders - Customer order history

Development Commands

Setup and Run

# Create virtual environment
python3 -m venv .venv
source ./.venv/bin/activate  # macOS/Linux
# OR
.venv\Scripts\activate  # Windows

# Install dependencies  
pip install -r requirements.txt

# Run the application
python app.py

Database Management

# Database is auto-created on first run
# To reset database, simply delete ecommerce.db and restart app
rm ecommerce.db && python app.py

Testing Access

• Application URL: http://127.0.0.1:5000
• Staff Login: username staff, password staff
• Guest Checkout: Available without account creation

Code Organization Patterns

Authentication & Authorization

• Uses Flask sessions for user state
• login_required() decorator with optional role checking
• Role-based access: customer and staff
• Staff-only routes protected by role validation

Database Pattern

• get_db() helper returns SQLite connection with Row factory
• Database auto-initialization via init_db_if_missing()
• Schema and seed data separated into schema.py

Cart Management

• Session-based cart storage (session['cart'])
• Cart structure: {product_id: quantity}
• Cart operations maintain state across requests

Order Processing

• Orders support both registered users and guest checkout
• Order status workflow managed by staff via /fulfill portal
• Order items stored separately with quantity and unit price snapshots

Important Notes

• Security Warning: This uses plaintext passwords - FOR EDUCATIONAL USE ONLY
• Database: SQLite file-based database, not suitable for production
• Sessions: Uses simple Flask sessions, not production-ready
• Error Handling: Basic flash messaging system for user feedback

Common Development Tasks

Adding New Products

Products are seeded via schema.py - modify the products list in seed_data() function.

Modifying Order Status Flow

Update the next_map dictionary in the /advance/<order_id> route in app.py.

Template Customization

All templates extend base.html which includes Bootstrap 5 and navigation structure.

Database Schema Changes

Modify create_schema() in schema.py - delete ecommerce.db to recreate with new schema.