# Product Finder Project

## What This Project Is

This repository contains a Flask-based Product Finder application used to guide users
through product selection and provide product detail, accessory, search, and admin
workflows.

The current application is no longer a simple Flask conversion of a static quiz.
It now includes:
- modular blueprints
- login and session management
- location-aware access
- product management APIs
- shareable quiz URLs
- layered image preview support
- an optional SQLite backend

## Fastest Way To Run It

From the repository root:

```bash
cd app
../.venv/bin/python app.py
```

Then open:
- `http://127.0.0.1:8080/`
- `http://127.0.0.1:8080/quiz/`

## Recommended VS Code Tasks

Use the built-in tasks from the repository root:

- `Start Flask Server`
- `Process All Data`
- `Update Data Files from CSV`
- `Generate Bitwise Data`

`Process All Data` runs the two data-generation steps in sequence.

## Main Application Areas

### Authentication
- login page
- logout
- session info endpoint
- location selection for multi-location users

### Product Finder
- guided quiz flow at `/quiz/`
- advanced search page
- product list page
- product manager page
- direct product links at `/quiz/product/<product_code>`

### Images and Previews
- flat product images
- layered image previews
- Canvas API fallback routes for hierarchical image lookup
- layer transforms for mirrored door/hardware previews where configured

### Data Layer
- JSON is the default runtime backend
- SQLite support exists behind a config flag
- frontend quiz data is driven by JSON files in `app/data/`

## Important Files

- `app/app.py` - application entry point
- `app/blueprints/auth.py` - authentication/session logic
- `app/blueprints/users.py` - user management routes
- `app/blueprints/products.py` - quiz pages, product APIs, admin pages
- `app/blueprints/canvas.py` - Canvas API image routes
- `app/static/js/script.js` - quiz flow, URL state, search, previews
- `app/data/navigation.json` - quiz navigation structure
- `app/data/products.json` - product catalog data
- `app/data/accessories.json` - accessory data
- `app/data/product_bitwise.json` - bitwise lookup data

## Current Known Status

Implemented:
- modular Flask app structure
- login/session flow
- location-aware permissions
- user management
- product CRUD/search APIs
- quiz result filtering
- shareable URL state
- product deep links
- Canvas API image fallback system

Still incomplete:
- fully generic conditional question skipping based on navigation metadata
- automated tests
- decision on whether SQLite should become the default backend

## If You Are Updating Product Data

1. Update the source CSV used by the data-generation scripts.
2. Run `Process All Data`.
3. Restart the Flask server if needed.
4. Verify quiz results and product detail views.

## If You Are Picking Up Development

Start with these files:

1. `app/app.py`
2. `app/blueprints/products.py`
3. `app/static/js/script.js`
4. `app/data/navigation.json`
5. `app/config.py`

Those files define the main routing, quiz behavior, and backend mode.