CGW-Quote-Builder/information/START_HERE.md

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:

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.