01 — Product Overview

What is QuoteForge

A corporate server configuration and quotation tool. Operates in strict local-first mode: all user operations go through local SQLite; MariaDB is used only by synchronization and dedicated setup/migration tooling.

Features

For Users

Mobile-first interface — works comfortably on phones and tablets
Server configurator — step-by-step component selection
Automatic price calculation — based on pricelists from local cache
CSV export — ready-to-use specifications for clients
Configuration history — versioned snapshots with rollback support
Full offline operation — continue working without network, sync later
Guarded synchronization — sync is blocked by preflight check if local schema is not ready

Local Client Security Model

QuoteForge is currently a single-user thick client bound to localhost.

The local HTTP/UI layer is not treated as a multi-user security boundary.
RBAC is not part of the active product contract for the local client.
The authoritative authentication boundary is the remote sync server and its DB credentials captured during setup.
If the app is ever exposed beyond localhost, auth/RBAC must be reintroduced as an enforced perimeter before release.

Price Freshness Indicators

Color	Status	Condition
Green	Fresh	< 30 days, ≥ 3 sources
Yellow	Normal	30–60 days
Orange	Aging	60–90 days
Red	Stale	> 90 days or no data

Tech Stack

Layer	Stack
Backend	Go 1.22+, Gin, GORM
Frontend	HTML, Tailwind CSS, htmx
Local DB	SQLite (`qfs.db`)
Server DB	MariaDB 11+ (sync transport only for app runtime)
Export	encoding/csv, excelize (XLSX)

Product Scope

In scope:

Component configurator and quotation calculation
Projects and configurations
Read-only pricelist viewing from local cache
Sync (pull components/pricelists, push local changes)

Out of scope (removed intentionally — do not restore):

Admin pricing UI/API
Stock import
Alerts
Cron/importer utilities

Repository Structure

quoteforge/
├── cmd/
│   ├── qfs/main.go               # HTTP server entry point
│   ├── migrate/                  # Migration tool
│   └── migrate_ops_projects/     # OPS project migrator
├── internal/
│   ├── appmeta/                  # App version metadata
│   ├── appstate/                 # State management, backup
│   ├── article/                  # Article generation
│   ├── config/                   # Config parsing
│   ├── db/                       # DB initialization
│   ├── handlers/                 # HTTP handlers
│   ├── localdb/                  # SQLite layer
│   ├── middleware/               # Auth, CORS, etc.
│   ├── models/                   # GORM models
│   ├── repository/               # Repository layer
│   └── services/                 # Business logic
├── web/
│   ├── templates/                # HTML templates + partials
│   └── static/                   # CSS, JS, assets
├── migrations/                   # SQL migration files (30+)
├── bible/                        # Architectural documentation (this section)
├── releases/memory/              # Per-version changelogs
├── config.example.yaml           # Config template (the only one in repo)
└── go.mod

Integration with Existing DB

QuoteForge integrates with the existing RFQ_LOG database.

Hard boundary:

normal runtime HTTP handlers, UI flows, pricing, export, BOM resolution, and project/config CRUD must use SQLite only;
MariaDB access is allowed only inside internal/services/sync/* and dedicated setup/migration tools under cmd/;
any new direct MariaDB query in non-sync runtime code is an architectural violation.

Read-only:

lot — component catalog
qt_lot_metadata — extended component data
qt_categories — categories
qt_pricelists, qt_pricelist_items — pricelists
stock_log — stock quantities consumed during sync enrichment
qt_partnumber_books, qt_partnumber_book_items — partnumber book snapshots consumed during sync pull

Read + Write:

qt_configurations — configurations
qt_projects — projects

Sync service tables:

qt_client_schema_state — applied migrations state and operational client status per device (username + hostname) Fields written by QuoteForge: app_version, last_sync_at, last_sync_status, pending_changes_count, pending_errors_count, configurations_count, projects_count, estimate_pricelist_version, warehouse_pricelist_version, competitor_pricelist_version, last_sync_error_code, last_sync_error_text, last_checked_at, updated_at
qt_pricelist_sync_status — pricelist sync status

4.9 KiB Raw Blame History Unescape Escape