# 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 and operational client status per device (`username + hostname`)
  Fields written by QuoteForge:
  `last_applied_migration_id`, `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