# 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