# PriceForge Bible

The main architectural reference for developers and AI agents. Source of truth for the project.

---

## What is PriceForge

PriceForge is a price and pricelist manager built on top of MariaDB.

- **Runtime**: MariaDB-only, fail-fast (if DB is unavailable at startup — server exits)
- **Main UI**: `/admin/pricing`
- **Default port**: `8084`
- **Go module**: `git.mchus.pro/mchus/priceforge`

---

## Table of Contents

| File | Description |
|------|-------------|
| [architecture.md](architecture.md) | Stack, project structure, modules, routes |
| [pricelist.md](pricelist.md) | Pricelist types (Estimate / Warehouse / Competitor) and creation rules |
| [vendor-mapping.md](vendor-mapping.md) | partnumber → LOT mapping, bundles, ignore logic |
| [background-tasks.md](background-tasks.md) | Task Manager: Submit, polling, task types |
| [data-rules.md](data-rules.md) | Categories, data integrity rules |
| [patterns.md](patterns.md) | Code patterns: CSV export, streaming, virtual fields |
| [api.md](api.md) | All API endpoints |
| [operations.md](operations.md) | Config, commands, build, release |
| [history.md](history.md) | Architectural decisions and change log |

---

## Documentation Standards

- **Language**: All documentation in `bible/` is written in **English**.
- **Architectural decisions**: Every architectural decision MUST be recorded in [history.md](history.md) with date, rationale, constraints, and affected files. No exceptions.
- **Before user-requested commits**: If a user asks to create a commit, update relevant `bible/` docs in the same change set before committing.

---

## Hard Rules (for AI agents)

> These rules MUST NOT be violated when writing code.

1. **Warehouse pricelist** — only mapped partnumbers from `lot_partnumbers`. Unmapped partnumbers are excluded entirely.
2. **Categories** — always from `lot.lot_category`. Never derive from LOT name.
3. **Background tasks** — Task Manager only (`taskManager.Submit()`). Never use SSE.
4. **Vendor mapping** — 1:1 key `(vendor, partnumber)`. Composite mappings only via bundles.
5. **Home page** — redirect to `/admin/pricing`. Configurator, projects, export must not appear in the UI.
6. **Document decisions** — every architectural decision must be added to `bible/history.md`.