# Product Finder Application

## Overview

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:

```bash
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

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