CGW-Quote-Builder/app/README.md

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:

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.