This folder contains the active Flask application for the Product Finder project. The app is structured around blueprints and serves a guided product-selection flow, admin tooling, and image preview APIs from the same codebase.

Current Architecture

app/
├── app.py                  # Flask app entry point and blueprint registration
├── config.py               # Backend/config toggles
├── data_access.py          # Chooses JSON or SQLite backend
├── data_access_json.py     # JSON-backed data operations
├── data_access_sqlite.py   # SQLite-backed data operations
├── models.py               # SQLAlchemy models for SQLite mode
├── blueprints/
│   ├── auth.py             # Login, logout, session, location selection
│   ├── users.py            # User CRUD and password management
│   ├── products.py         # Quiz pages, product APIs, admin pages
│   └── canvas.py           # Layered image fallback API
├── static/
│   ├── css/styles.css      # Main application styles
│   ├── js/script.js        # Quiz flow, URL state, search, previews
│   └── images/             # Product and layered image assets
├── templates/              # Flask templates
└── data/                   # JSON data files used by the app

Implemented Features

Authentication and Session Flow

Username/password login
Session-backed authentication
Active/inactive user checks
Multi-location session support with location selection
Permission checks via can_user(...)

User Management

List users
Create users
Delete users
Toggle active status
Change passwords
Download user data JSON

Product Finder

Quiz flow served at /quiz/
URL-based state restoration with query params:
- b for bitwise state
- q for current question/results state
- p for direct product links
Product results grid with clickable product cards
Product detail page with configuration controls
Share buttons for results and product-detail URLs
Browser back/forward support via popstate

Product Management and Search

Advanced search page
Product listing page with search and pagination API
Product manager page
Product CRUD API endpoints
Product attributes API endpoint

Image Systems

Flat-image preview support
Static layered-image support
Canvas API fallback system for hierarchical image lookup
Layer transforms for flipped/mirrored previews where configured

Data Backends

JSON backend is the current default
SQLite backend is supported behind USE_DATABASE = True in config.py
Data-access calls are routed through data_access.py

Important Routes

App-Level Routes

/ - Authenticated home page
/test - Basic app health page
/init-db - Create SQLite tables when database mode is enabled

Auth Routes

/login
/select-location
/api/login
/api/select-location
/api/session
/logout

Product Routes

/quiz/
/quiz/index
/quiz/advanced-search
/quiz/list
/quiz/manage
/quiz/product/<product_code>
/quiz/api/products
/quiz/api/products/search
/quiz/api/products/<product_code>
/quiz/api/product-attributes

Canvas API Routes

/api/canvas/<product_code>/<layer>
/api/canvas/<product_code>/info
/api/canvas/test

Local Development

From the repository root:

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

Open:

http://127.0.0.1:8080/
http://127.0.0.1:8080/quiz/

Data Update Workflow

If product source data changes, use the VS Code tasks from the repository root:

Update Data Files from CSV
Generate Bitwise Data
Process All Data

These regenerate the JSON files consumed by the quiz and filtering logic.

Current Limitations

Generic conditional-question evaluation is not fully implemented in the frontend. The current flow works with the generated navigation structure and a small amount of hardcoded branching, but it does not yet use a reusable resolveNextQuestion style engine for all conditional prompts.
SQLite support exists, but the project currently runs in JSON mode by default.
There is no automated test suite in this repository yet; validation is currently manual.

Recommended Next Work

Finish generic conditional navigation so conditional metadata in navigation.json is evaluated uniformly.
Add smoke tests for login, quiz state restoration, and product detail deep links.
Decide whether SQLite should remain optional or become the default backend.