QuoteForge/bible/01-overview.md

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 for synchronization.

---

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

User Roles

Role	Permissions
viewer	View, create quotes, export
editor	+ save configurations
pricing_admin	+ manage prices and alerts
admin	Full access, user management

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 + server admin)
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
│   ├── lotmatch/                 # Lot matching logic
│   ├── 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:

Read-only:

• lot — component catalog
• qt_lot_metadata — extended component data
• qt_categories — categories
• qt_pricelists, qt_pricelist_items — pricelists

Read + Write:

• qt_configurations — configurations
• qt_projects — projects

Sync service tables:

• qt_client_local_migrations — migration catalog (SELECT only)
• qt_client_schema_state — applied migrations state
• qt_pricelist_sync_status — pricelist sync status