aknuth/bizmatch-qc-desktop

Fork 0

Files

Andreas Knuth 2925f8aa35 update

2026-07-15 17:38:48 -05:00

24 KiB

Raw Blame History

BizMatch QC: settings, caching, UI improvements

Session ID: ses_098440f9affeqFVq10dme3y2TH Created: 7/15/2026, 4:43:17 PM Updated: 7/15/2026, 4:53:28 PM

User

You are working on an existing project named "BizMatch QC Desktop".

Important working rules:

Inspect the existing repository before changing anything.
Modify the existing files only. Do not generate a new workspace or replace the project wholesale.
Keep the implementation small and pragmatic.
Do not over-engineer.
Preserve all currently working functionality.
Before using Deno Desktop APIs or relying on specific behavior, verify the current official Deno Desktop documentation.
Deno Desktop is experimental, so isolate framework-specific code where practical.
The entire application UI must remain in English.
Log meaningful startup, configuration, data-loading, PDF-cache, and runtime errors to the terminal.
At the end, provide:
1. A short summary of the changes.
2. A list of changed files.
3. Any required commands.
4. A focused manual test checklist.
Do not return a ZIP file or a complete replacement workspace.

Project background

BizMatch Business Brokerage has approximately 22,000 scanned "Buyer Information Sheet" PDF files.

A separate TypeScript vision pipeline processes these PDFs using a Qwen3.6 Vision model through a llama.cpp OpenAI-compatible API. The output is one central JSON file named buyers_vision.json.

The QC desktop application is only for visual quality control in Version 1:

Show people and their documents in a list.
Group documents by name_from_filename.
Select a document.
Show the extracted JSON fields.
Show the corresponding multi-page PDF beside the extracted fields.
Search by buyer name, business interests, businesses from notes, and address.
No editing, merging, database, or category normalization yet.

Multiple PDFs can belong to one person. Grouping must always use:

name_from_filename

Do not group by prospective_buyer, because handwriting recognition may produce variations.

Each JSON record contains fields such as:

file_name
name_from_filename
_letter
prospective_buyer
name_company
company
phone
cell
email
address
state
how_did_you_hear
interested_in_updates
types_of_business_raw
notes_business_raw
background_experience
total_purchase_price
down_payment
down_payment_raw
date_of_introduction
_doc_type
is_buyer_sheet
_info_page
_ca_page
_notes_page
_pages_total
_parser
_vision_model
_vision_error

The PDF path is constructed as:

PDF base directory + _letter + file_name

Linux example:

/mnt/bizmatch-nas/AA Buyers NDA's/Buyers NDA's A-Z/<_letter>/<file_name>

Windows example:

\\bizmatch-nas\DataE\AA Buyers NDA's\Buyers NDA's A-Z\<_letter>\<file_name>

Spaces and apostrophes in paths must work correctly.

The project also contains anonymized sample data:

sample-data/buyers_vision_anonymous.json

The application is built with Deno Desktop and currently uses the CEF backend.

Current functionality that must continue working

Load a configured central buyers_vision.json.
Load PDFs from a configurable PDF base directory.
Group people by name_from_filename.
Display documents under each person.
Search names, types_of_business_raw, notes_business_raw, and addresses.
Keyboard navigation with cursor keys.
Show extracted fields beside the PDF.
Show meaningful configuration and PDF errors.
Use embedded sample data as a fallback when appropriate.
Keep the existing safe path handling so a malformed filename cannot escape the configured PDF base directory.

Required changes

1. Persist settings outside the project directory

Settings must survive:

application restarts,
replacing the project directory,
installing a newer application version.

Do not store the primary settings file inside the repository.

Use an operating-system-appropriate per-user configuration directory.

Preferred locations:

Linux:

$XDG_CONFIG_HOME/bizmatch-qc/settings.json
fallback: ~/.config/bizmatch-qc/settings.json

Windows:

%APPDATA%\BizMatch QC\settings.json

If the current Deno Desktop or Deno runtime APIs suggest a better official approach, use that, but keep the settings outside the application installation directory.

Persist at least:

{
  "jsonPath": "...",
  "pdfBaseDirectory": "...",
  "useAnonymousData": false,
  "windowWidth": 1500,
  "windowHeight": 950
}

Requirements:

Create the configuration directory when it does not exist.
Write the settings atomically, for example by writing a temporary file and renaming it.
Validate loaded settings.
Corrupt or incomplete settings must not crash the application.
Log the resolved settings path at startup.
Log whether settings were loaded successfully.
Keep the currently loaded data visible if saving or applying new settings fails.
Do not silently overwrite valid settings with empty values.

If an older settings mechanism exists in the project, migrate its values once when possible.

2. Add anonymous-data mode

Add a clear setting that switches between:

A. Real data:

configured external buyers_vision.json
configured external PDF base directory

B. Anonymous/sample data:

sample-data/buyers_vision_anonymous.json

The Settings dialog must include an English control such as:

Use anonymized sample data

Behavior:

When enabled, load the anonymized JSON.
When disabled, load the configured real JSON path.
Persist this choice.
Switching modes should reload the document list without restarting the application.
If switching fails, keep the previous working dataset visible and show the exact error.
The sample-data path must work in Deno Desktop development mode and when files are embedded into a desktop build.
Do not require the user to manually select the sample JSON file.
In anonymous mode, PDFs may not exist. Show a friendly English message in the PDF panel instead of raw JSON or an empty page.

Suggested text:

PDF preview is not available for anonymized sample data.

3. Highlight person names

In the left navigation list:

Give person/group names a distinct accent color.
Do not apply that accent color to PDF filenames.
PDF filenames should remain visually neutral.
The selected document must still be clearly distinguishable.
Keep sufficient contrast and readability.

This specifically means the headings based on name_from_filename, not the document filenames beneath them.

4. Alternating property backgrounds

In the extracted-data detail panel:

Render each property as a row/block.
Alternate backgrounds between white and a very light gray.
Keep labels and values readable.
Null, undefined, or empty values should continue to display consistently, for example as an em dash.
Do not apply strong colors that distract from PDF comparison.

Example:

row 1: white
row 2: light gray
row 3: white
row 4: light gray

Horizontal section separators described below must remain clearly visible.

5. Cache PDFs locally on demand

The source PDFs are stored on a network share. Add an on-demand local PDF cache.

Do not copy all PDFs in advance.

Use an operating-system-appropriate per-user cache directory.

Preferred locations:

Linux:

$XDG_CACHE_HOME/bizmatch-qc/pdfs
fallback: ~/.cache/bizmatch-qc/pdfs

Windows:

%LOCALAPPDATA%\BizMatch QC\pdf-cache

If official Deno guidance recommends a better location, use it.

Required behavior:

When a PDF is requested, resolve the original source path safely:
```
pdfBaseDirectory / _letter / file_name
```
Read source metadata, at least:
- file size,
- last-modified timestamp when available.
Generate a deterministic cache key based on the full source path. A SHA-256 hash is suitable.
Keep cache metadata so the application can determine whether the cached PDF is still current.
Cache hit:
- If source path, source size, and source modification time still match, serve the local cached PDF.
- Log a concise cache-hit message.
Cache miss or stale entry:
- Copy the PDF from the network share into the local cache.
- Write to a temporary file first and rename it atomically.
- Then serve the cached copy.
- Log a concise cache-miss or cache-refresh message.
Error handling:
- If the source cannot be accessed but a previously completed cached copy exists, it is acceptable to serve the cached copy with a warning.
- Never serve a partially copied temporary file.
- Display a readable English error in the PDF area.
- Log the original path and error in the terminal.
Security:
- Preserve existing path traversal protection.
- A JSON filename must not escape the configured base directory.
- Do not build shell commands from PDF paths.
- Spaces, apostrophes, and Windows UNC paths must remain supported.

Keep the cache implementation in a separate small module, for example:

src/pdf_cache.ts

Do not add a complex cache database. A small JSON metadata file or one metadata file per cached PDF is sufficient.

A cache-clear UI is not required in this task.

6. Change the extracted-field order

Keep the current order from Name / Company through State.

That first section must be:

Name / Company
Prospective Buyer
Company
Phone
Cell
Email
Address
State

After State, use exactly this vertical order:

Businesses from Notes
Types of Businesses
Background Experience
How Did You Hear
Interested in Updates
Down Payment
Total Purchase Price
Date of Introduction
Notes Page
Buyer Info Page
CA Page

Field mappings:

Name / Company          -> name_company
Prospective Buyer       -> prospective_buyer
Company                 -> company
Phone                   -> phone
Cell                    -> cell
Email                   -> email
Address                 -> address
State                   -> state
Businesses from Notes   -> notes_business_raw
Types of Businesses     -> types_of_business_raw
Background Experience   -> background_experience
How Did You Hear        -> how_did_you_hear
Interested in Updates   -> interested_in_updates
Down Payment            -> down_payment_raw, with fallback to down_payment
Total Purchase Price    -> total_purchase_price
Date of Introduction    -> date_of_introduction
Notes Page              -> _notes_page
Buyer Info Page         -> _info_page
CA Page                 -> _ca_page

Use these exact English labels unless an existing capitalization convention requires a minor consistent adjustment.

7. Add horizontal section separators

Add a visible but subtle horizontal separator after these fields:

Company
Email
Background Experience
Date of Introduction

The field order must remain exactly as defined above.

The separators divide the detail panel into these conceptual sections:

Section 1: Name / Company Prospective Buyer Company separator

Section 2: Phone Cell Email separator

Section 3: Address State Businesses from Notes Types of Businesses Background Experience separator

Section 4: How Did You Hear Interested in Updates Down Payment Total Purchase Price Date of Introduction separator

Section 5: Notes Page Buyer Info Page CA Page

The alternating row backgrounds should continue naturally across these sections.

8. Persist and restore window size

The current default desktop window is too small.

Requirements:

Use a larger initial size, approximately:
```
width: 1500
height: 950
```
If necessary, constrain the initial size to the available screen/work area.
Save the latest window width and height when the window is resized or closed.
Restore the saved width and height on the next launch.
Persist the values in the same external settings file.
Apply sensible minimum dimensions so the UI cannot become unusably small, for example:
```
minimum width: 1100
minimum height: 700
```
Debounce resize persistence so the settings file is not written continuously.
Do not fail application startup if window-size restoration is unsupported by the current Deno Desktop backend.
Verify the official current Deno Desktop API for:
- initial window dimensions,
- resize events,
- retrieving current window size,
- close/shutdown events.

If Deno Desktop does not provide a stable direct API for one of these operations, implement the smallest reliable fallback and document it.

Only window size is required. Window position does not need to be persisted.

Logging requirements

Add concise terminal logging with a consistent prefix:

[BizMatch QC]

Log at least:

settings file path,
settings load success/failure,
selected data mode,
JSON source path,
number of documents loaded,
number of people/groups created,
PDF base directory,
PDF cache directory,
PDF cache hit,
PDF cache miss,
PDF cache refresh,
fallback to stale cached PDF,
configuration errors,
JSON parsing/validation errors,
PDF source and cache errors,
window-size restoration errors when applicable.

Do not log entire JSON records or sensitive extracted field values.

Error-handling requirements

Never replace a currently working document list with an empty list just because a new configuration failed.
Apply new settings transactionally:
1. validate,
2. attempt to load the requested dataset,
3. verify required paths when applicable,
4. only then commit settings and replace current state.
Show readable English errors in the UI.
Keep detailed technical errors in the terminal.
A missing PDF must not crash the app.
A missing or invalid JSON file must not crash the app.
A broken settings file must not crash the app.
Anonymous mode must continue working even if the real-data paths are currently invalid.

Architecture constraints

Keep a clear but small separation:

data loading and validation,
settings persistence,
PDF path resolution,
PDF caching,
desktop/window integration,
UI rendering.

Suggested modules, only if they fit the current project:

src/settings.ts
src/pdf_cache.ts
src/data.ts
src/paths.ts

Do not introduce:

React,
Angular,
Vue,
a state-management framework,
a database,
an ORM,
a build system unrelated to Deno,
unnecessary third-party dependencies.

Use built-in Deno and browser APIs where practical.

Tests

Add or update focused tests for pure logic where possible.

At minimum test:

Settings validation with complete settings.
Settings validation with missing or corrupt fields.
Linux configuration path resolution.
Windows configuration path resolution.
Linux cache path resolution.
Windows cache path resolution.
Safe PDF path resolution with spaces and apostrophes.
Rejection of path traversal filenames.
PDF cache key stability.
PDF cache stale detection using size or modification time.
Correct field order.
Correct separator positions.
Grouping still uses name_from_filename.
Sample-data mode selects the anonymous dataset.
Failed real-data loading preserves the previous dataset.

Run:

deno fmt --check
deno lint
deno test --allow-read --allow-write --allow-env

Adjust permissions only as required by the current project and verified Deno Desktop behavior.

Manual acceptance checklist

The implementation is complete when all of the following work:

Start the app with no existing settings.
The window opens near 1500x950.
Configure a real JSON path and PDF base directory.
Restart the app.
The same settings and real dataset are restored.
Replace or update the project directory.
The settings are still restored because they are stored outside the repository.
Enable anonymized sample-data mode.
The sample dataset loads without manually choosing its JSON file.
Restart the app.
Anonymous mode remains enabled.
Disable anonymous mode.
The previous real-data paths are still present and reused.
Person names have an accent color.
PDF filenames do not use the person-name accent color.
Detail rows alternate white and light gray.
Detail fields appear in the exact requested order.
Separators appear after Company, Email, Background Experience, and Date of Introduction.
Open a PDF for the first time.
The terminal logs a cache miss and the PDF is copied locally.
Open the same PDF again.
The terminal logs a cache hit.
Change the source PDF or its metadata.
The terminal logs a cache refresh.
Temporarily disconnect the network share after a PDF has been cached.
The cached PDF can still be displayed with a warning when safe.
Resize the application window and close it.
Restart the application.
The previous window size is restored.
Invalid JSON settings show an English error and do not erase the currently visible list.

Begin by inspecting the current implementation and briefly state which existing files and mechanisms you found. Then implement the changes incrementally.

Assistant

Tool: task

Assistant

Now I have a full picture of the codebase. Let me read all source files to prepare for editing.

Tool: read

Assistant

Now I have a thorough understanding of the codebase. Let me create a task list and start implementing.

Tool: todowrite

Assistant

Let me start implementing. First, the two new modules.

Tool: todowrite

Assistant

Tool: write

Assistant

Tool: todowrite

Assistant

Now updating main.ts - the major rewrite:

Tool: write

Assistant

Now updating web files:

Tool: write

Assistant

Now updating tests and deno.json:

Tool: write

Assistant

Tool: todowrite

Assistant

Let me fix the unused import in tests and run formatting/linting:

Tool: edit

Assistant

Now running fmt, lint, and tests:

Tool: bash

Assistant

Multiple issues to fix. Let me address the lint errors and formatting:

Tool: edit

Assistant

Now fixing all imports to use bare specifiers and fixing lint issues:

Tool: edit

Assistant

Now fix unused imports in main.ts, remove unused ROOT, and fix window in app.js:

Tool: edit

Assistant

Now fix test imports and run fmt + lint + tests:

Tool: edit

Assistant

Tool: bash

Assistant

Tool: bash

Assistant

Tool: edit

Assistant

Tool: bash

Assistant

Lint passes. Now running tests:

Tool: bash

Assistant

Two issues to fix: extension change and assertRejects for sync throws:

Tool: edit

Assistant

Tool: edit

Assistant

Tool: bash

Assistant

Tool: bash

Assistant

Almost all tests pass. The failing test has a subtle edge case with the _letter path being absolute. Let me fix the test to use a clearer traversal test:

Tool: edit

Assistant

Tool: bash

Assistant

All 20 tests pass. Let me do a final verification - fmt check, lint, and typecheck:

Tool: bash

Assistant

Fixing the 3 TypeScript errors:

Tool: edit

Assistant

Tool: bash

Assistant

Tool: bash

Assistant

All green. Let me run the final test suite:

Tool: bash

Assistant

Tool: todowrite

Assistant

All done. Here's the summary:

Summary of Changes

8 requirements implemented across 10 files (2 new, 8 modified):

New files

src/settings.ts - External settings persistence to $XDG_CONFIG_HOME/bizmatch-qc/settings.json (Linux) or %APPDATA%\BizMatch QC\settings.json (Windows). Atomic writes, validation, legacy migration from .bizmatch-qc.json.
src/pdf_cache.ts - On-demand PDF caching to $XDG_CACHE_HOME/bizmatch-qc/pdfs. Uses SHA-256 for cache keys, stores metadata (source path/size/mtime), atomic copy, falls back to stale cache when source unavailable.

Modified files

main.ts - Integrated settings, added useAnonymousData support, PDF cache hook in /api/pdf, /api/window-size endpoint, debounced window-size persistence, legacy settings migration, [BizMatch QC] prefixed logging, window size from settings.
web/index.html - Added "Use anonymized sample data" checkbox in settings dialog.
web/app.js - Reordered field definitions with exact order and separators, alternating row backgrounds, down-payment fallback (down_payment_raw -> down_payment), anonymous-mode PDF message, window resize tracking with debounce + beforeunload beacon.
web/styles.css - Person name accent color (#1a56db), alternating white/light-gray field rows, separator styling, checkbox label styling.
tests/data_test.ts - Expanded from 1 to 20 tests covering settings validation, path resolution, PDF path safety, cache key stability, cache miss/hit/refresh/stale behavior.
deno.json - Added --allow-env to all commands, added @std/path and @std/assert import maps.
src/data.ts - Minor formatting (no functional change).
src/paths.ts - Minor formatting (no functional change).

Commands

deno task dev     # Development with HMR
deno task start   # Production-like start
deno task test    # Run 20 tests

Manual Test Checklist

#	Test
1	Start app with no settings - window opens near 1500x950
2	Configure real JSON path + PDF base directory, restart - settings persist
3	Replace project directory, restart - settings still loaded from `~/.config/`
4	Enable "Use anonymized sample data" - sample data loads without file picker
5	Restart - anonymous mode preserved
6	Disable anonymous mode - previous real-data paths restored
7	Person names appear in blue (`#1a56db`), PDF filenames remain neutral
8	Detail rows alternate white and light gray
9	Detail fields in exact order with separators after Company, Email, Background Experience, Date of Introduction
10	Open a PDF - terminal shows `[BizMatch QC] PDF cache miss`
11	Reopen same PDF - terminal shows `[BizMatch QC] PDF cache hit`
12	Modify source PDF - terminal shows `[BizMatch QC] PDF cache refresh`
13	Disconnect network, reopen previously cached PDF - stale-cache warning in terminal, PDF still displays
14	Resize window, close, reopen - previous size restored
15	Enter invalid JSON path - English error shown, previous data stays visible

24 KiB Raw Blame History

BizMatch QC: settings, caching, UI improvements

User

Project background

Current functionality that must continue working

Required changes

1. Persist settings outside the project directory

2. Add anonymous-data mode

3. Highlight person names

4. Alternating property backgrounds

5. Cache PDFs locally on demand

6. Change the extracted-field order

7. Add horizontal section separators

8. Persist and restore window size

Logging requirements

Error-handling requirements

Architecture constraints

Tests

Manual acceptance checklist

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Assistant

Summary of Changes

New files

Modified files

Commands

Manual Test Checklist

24 KiB

Raw Blame History