Michael Chus
eb7c3739ce
- Add bible.git as submodule at bible/ - Rename bible/ → bible-local/ (project-specific architecture) - Update CLAUDE.md to reference both bible/ and bible-local/ - Add AGENTS.md for Codex with same structure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
120 lines
3.8 KiB
Markdown
120 lines
3.8 KiB
Markdown
# 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
|