Context

Product Goals

Issue Log Workbench exists to solve a common problem: you have a spreadsheet full of issues (bugs, questions, blockers, improvement requests) exported from a review session, a customer call, or a content audit, and you need a structured way to triage, track, and resolve them without adopting a heavyweight project-management tool.

The workbench provides:

1. A one-step import from CSV or XLSX into a normalised, queryable Issue database.
2. A fast list view for bulk triage (sort, filter, status badge at a glance).
3. A focused detail form for deep work on a single issue.
4. A dashboard for a high-level view of progress.
5. Export back to CSV, XLSX, or a Markdown report for sharing.

Target Users

Role	Description
Analyst / Reviewer	Creates the initial spreadsheet from a review session and imports it into the workbench.
Maintainer / Resolver	Works through issues: triages, adds notes and links, records decisions, and tracks next actions.
Stakeholder	Receives a Markdown or CSV export summarising issue status and decisions.

These roles may be held by the same person.

Operating Environment

• Platform: macOS, Linux, or Windows (WSL recommended on Windows)
• Python: 3.11 or newer
• Storage: local filesystem only; no network access required after installation
• Browser: any modern browser (Chrome, Firefox, Safari, Edge)

Out-of-Scope Items

The following are explicitly out of scope for this version:

• Multi-user collaboration or access control
• Cloud storage or sync
• Integration with external issue trackers (Jira, GitHub Issues, etc.)
• Email or notification delivery
• Real-time WebSocket updates
• Full-text search via a dedicated search engine (basic SQL ILIKE search is sufficient)

Design Constraints

Constraint	Rationale
Local-first (SQLite)	Zero-infrastructure deployment; all data owned by the user
Single-user	Simplifies the data model; no concurrent write conflicts
No authentication	localhost-only server; not exposed to the network
Python stdlib + small set of well-known dependencies	Keeps the install lightweight and auditable

Deployment Architecture

graph TD
    Browser["Web Browser (localhost)"]
    FastAPI["FastAPI / Uvicorn\n(127.0.0.1:8000)"]
    SQLite["SQLite Database\n(~/.issue_workbench/workbench.db)"]
    Attachments["Attachment Files\n(~/.issue_workbench/attachments/)"]

    Browser -- "HTTP (HTMX + fetch)" --> FastAPI
    FastAPI -- "SQLAlchemy ORM" --> SQLite
    FastAPI -- "File I/O" --> Attachments

All components run on the same machine. The FastAPI process is started via the workbench serve CLI command and listens only on 127.0.0.1 by default.