SmartShop AI is a supporting full-stack portfolio project built with React and Django REST Framework. It demonstrates grounded AI-assisted shopping workflows over a 50-product synthetic catalogue, using OpenAI first, Gemini second, and deterministic fallbacks when providers are unavailable or unusable. It is a controlled local demonstration, not a production commerce platform.
Supporting portfolio project · 50-product synthetic catalogue · 31 backend tests passed · Frontend build verified
- Grounded natural-language product search that returns catalogue records.
- Controlled-profile recommendations based on synthetic purchase patterns.
- A catalogue-grounded virtual shopping assistant.
- Dynamic product descriptions with explicit source disclosure.
- Review summaries derived only from stored synthetic reviews.
- Clear provider, deterministic fallback, stored-data, and unavailable states.
- 50 products across six categories, supported by 125 reviews and 16 purchases.
- Responsive and accessibility improvements verified across desktop, tablet, and mobile.
- Django system check, 31 backend tests, and the frontend production build passed.
- Portfolio Status
- Problem and Intended Demonstration
- Main Features
- Technology Stack
- System Architecture
- Controlled Catalogue and Demo Profiles
- AI Grounding and Fallback Behaviour
- Project Structure
- Local Setup
- Environment Variables
- API Overview
- Testing and Verification
- Implemented and Intentionally Absent Scope
- Security and Privacy Boundaries
- Known Limitations
- AI-Assisted Development Disclosure
- Screenshots
- Licence
- Contact
- Repository: github.com/derekwongha/smartshop-ai
- Demonstration: verified local application using controlled synthetic data.
- Deployment: the application is not publicly deployed.
- Evidence: four approved screenshots are embedded below.
SmartShop demonstrates how generative providers can support catalogue discovery without becoming the source of truth. Product results are grounded in database records, review summaries use stored evidence, provider failures degrade to identified fallbacks, and synthetic profiles provide recommendation context without pretending to be authenticated customers.
The project intentionally focuses on AI-assisted catalogue workflows. It is not a complete online store and does not claim production customers, commerce operations, checkout, or payment processing.
- Grounded search: natural-language queries are matched to valid catalogue products.
- Controlled recommendations: two synthetic profiles demonstrate purchase-pattern recommendations.
- Virtual assistant: responses and product cards remain grounded in the current catalogue.
- Dynamic descriptions: provider output is validated, with a truthful stored-description fallback.
- Review summaries: summaries use only reviews stored for the selected synthetic product.
Every workflow returns source metadata so the interface can distinguish provider-generated, deterministic fallback, stored-data, and unavailable results.
| Area | Technology and verified version |
|---|---|
| Backend runtime | Python 3.11.1 |
| Backend | Django 5.2.14; Django REST Framework 3.17.1 |
| Database | MySQL 8.0.45; mysqlclient 2.2.8 |
| AI providers | OpenAI SDK 2.52.0; Google Gen AI SDK 2.13.0 |
| Frontend | React 19.2.7; Vite 8.0.16; Axios 1.19.0; plain CSS |
| Verified frontend runtime | Node.js 22.16.0 |
React and Vite run in the browser and send JSON requests through Axios to Django REST Framework. Django applies workflow controls, accesses MySQL through the ORM, and validates provider-selected products against catalogue records. OpenAI and Gemini are optional backend-only integrations; provider keys never enter the frontend.
- 50 products: Electronics 9; Accessories 9; Home & Office 9; Fitness 8; Fashion 8; Education 7.
- Supporting records: 125 controlled synthetic reviews and 16 controlled synthetic purchases.
- Profiles:
tech-studyandfitness-sportsprovide demonstration context; they are not authentication. - Imagery: 44 localized product photographs and six deliberate category fallbacks.
No real customer data is required or intended.
When configured, SmartShop attempts OpenAI first and Gemini second. Provider-selected names or identifiers are resolved against current catalogue records before products are returned. Each provider has an eight-second timeout, SDK retries are disabled, and application retries are bounded by the two-provider order.
Safe deterministic catalogue logic keeps search, recommendations, and assistant workflows useful when providers fail or return unusable results. Product descriptions can fall back to stored catalogue text. Review summaries use stored reviews only. If no safe result exists, the API returns an explicit unavailable state rather than inventing content.
Source metadata identifies each outcome. Scoped demo throttles limit search and assistant requests to 10 per minute, recommendations to 6 per minute, and product-detail generation to 12 per minute. These are demonstration controls, not production security.
SmartShop/
├── SmartShop/ # Django configuration
├── smartshop_backend/ # Models, API, tests, migration, controlled seed
├── SmartShop-frontend/ # React/Vite client and local product assets
├── docs/ # Architecture and approved screenshots
├── .env.example
├── ASSET_PROVENANCE.md
├── LICENSE
├── manage.py
└── requirements.txt
- Python 3.11
- Node.js compatible with Vite 8; Node 22.16.0 was verified
- MySQL 8.x
git clone https://github.com/derekwongha/smartshop-ai.git
Set-Location smartshop-ai
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .envOn macOS or Linux, use source .venv/bin/activate and cp .env.example .env.
Create an empty local MySQL database matching DB_NAME, set local credentials in the ignored .env, then use only the managed schema and controlled seed path:
python manage.py check
python manage.py migrate
python manage.py seed_demo_data --dry-run
python manage.py seed_demo_data
python manage.py runserver
In a second terminal:
cd SmartShop-frontend
npm ci
npm run dev
| Classification | Variables |
|---|---|
| Required | SECRET_KEY, DB_NAME, DB_USER, DB_PASSWORD |
| Local defaults or optional | DEBUG, ALLOWED_HOSTS, DB_HOST, DB_PORT, OPENAI_API_KEY, OPENAI_MODEL, GEMINI_API_KEY |
Provider keys may be blank. They belong only in the ignored backend .env; SmartShop does not use Vite environment variables for provider secrets.
| Method and route | Purpose |
|---|---|
GET /api/products/ |
Retrieve the catalogue |
POST /api/smart-search/ |
Grounded natural-language search |
POST /api/recommend/<profile_key>/ |
Controlled-profile recommendations |
POST /api/virtual-assistant/ |
Catalogue-grounded assistant response |
POST /api/products/<product_id>/dynamic-description/ |
Product description with source disclosure |
POST /api/products/<product_id>/summarize-reviews/ |
Summary of stored synthetic reviews |
Verified on 5 August 2026:
- Django system check passed.
- 31 backend tests passed.
- Frontend production build passed.
- Desktop, tablet, and mobile verification passed without broken images or horizontal overflow.
- Full and production-only npm audits reported no known vulnerabilities at the time of verification.
- No live provider request was required by the automated tests.
The project currently has no frontend automated test suite or lint script. Dependency audit results are time-bound and should be rechecked after changes.
Implemented: catalogue retrieval, grounded search, controlled recommendations, assistant responses, dynamic descriptions, stored-review summaries, deterministic fallbacks, scoped throttling, and controlled ORM seed data.
Intentionally absent: production authentication, persistent cart or wishlist, checkout, payment, order fulfilment, production administration, and public application deployment.
- Demonstration records are synthetic.
- Demo profile selectors are not authentication.
- Provider secrets remain backend-only and ignored locally.
- Provider-selected products are checked against catalogue records.
- Review summaries use stored synthetic evidence only.
- Throttling is scoped for a demonstration, not production-grade abuse prevention.
- No production customer authentication or account workflow.
- No cart persistence, wishlist persistence, checkout, or payment processing.
- No frontend automated test suite or lint script.
- No public application deployment.
- Provider availability and output can vary; identified fallbacks preserve only safe supported workflows.
- Six products use deliberate project-owned category illustrations instead of product photographs.
AI tools supported parts of implementation, debugging, image research, and documentation. I defined the requirements, directed the architecture and implementation decisions, reviewed generated outputs, tested the application, verified the final results, and own the final decisions and presentation.
Grounded catalogue search with deterministic fallback
Controlled-profile recommendations grounded in purchase patterns
Catalogue-grounded virtual shopping assistant
Product details with truthful stored-description fallback
SmartShop's project-owned source and documentation are available under the MIT License. See ASSET_PROVENANCE.md for image, typography, diagram, and screenshot provenance. Third-party material remains subject to its own terms.
- SmartShop AI repository
- Professional contact details are available through Derek Wong's portfolio website.