Individual and Jwellery Account Setup done

kifi_context.md

@@ -1,7 +1,7 @@
 # Kifi Project Context
 
 ## Overview
-Kifi is a financial and inventory management application designed to handle strict accounting principles along with inventory, vendor, and business operations.
+Kifi is a financial and inventory management application designed to handle strict accounting principles along with inventory, vendor, and business operations. It supports a specialized "Jewellery Business Mode".
 
 ### Components
 - **kifi-app**: Flutter mobile frontend.
@@ -11,31 +11,49 @@ Kifi is a financial and inventory management application designed to handle stri
 ## Core Features & Architecture
 
 ### 1. Accounting System
-- **Double-Entry Principle**: Strict double-entry accounting is mandated. Every financial entry must balance. 
-  - *Example*: Interest/bank fees on a Credit Card are recorded as a transfer: `From: CC -> To: Expense (Bank Charges/Interest)`.
+- **Double-Entry Principle**: Strict double-entry accounting is mandated. Every financial entry must balance.
 - **Entities**: The core entities are `Wallet` (which represents all forms of accounts/ledgers) and `Transaction`.
-- **Account Types (Natures)**: Accounts are categorized by `nature` (e.g., SAVINGS, INCOME, EXPENSE, PAYABLES, INVESTMENTS) and further specialized by `sub_nature`.
-- **Payables**: Specialized support for Credit Cards, Overdrafts (OD), EMIs, and Policy Premiums. Features configurable cycle dates, credit limits, and fixed amounts for recurring dues.
-- **Dashboard**: Features an `UpcomingDuesWidget` that proactively calculates and displays urgent dues based on cycle dates and negative balances.
+- **Account Types (Natures)**: Accounts are categorized by `nature` (e.g., SAVINGS, INCOME, EXPENSE, PAYABLES, INVESTMENTS).
+- **Payables**: Specialized support for Credit Cards, OD, EMIs, and Policy Premiums. Features configurable cycle dates and limits.
+- **Automated Ledger Mapping (`LedgerService`)**: 
+  - **Purchases**: Receiving a PO automatically debits `Inventory Asset` and credits the specific `Vendor Payable` wallet.
+  - **Sales**: Finalizing an Invoice automatically debits `Customer AR` and credits `Sales Revenue`.
+  - Wallets act as formal Chart of Accounts (COA) ledgers generated automatically on demand.
 
-### 2. Inventory Management
-- Supports Products, Categories, Unit of Measure (UOM), and Bills of Material (BOM).
-- Product pricing can follow auto-calculated rules.
-- Images are uploaded as Multipart form data, converted to Base64 in the backend, and sent to MinIO.
+### 2. Jewellery & Inventory Management
+- **Jewellery Business Mode**: When `BUSINESS` and `JEWELLERY` are selected, Kifi transitions into a robust jewellery ERP.
+- **Inventory Model**: 
+  - `Product` represents the master catalog definition (e.g., 22K Gold Ladies Ring).
+  - `InventoryItem` represents physical tags in the store. Each item is unique, storing exact gross/net/stone/fine weights, individual purchase costs, vendor reference, and uniquely tracking items via **HUID** or Barcode. HUID uniqueness forces 1:1 material tracking for those categories.
+- **Commodity Rates**: Commodity rates (e.g. Gold/Silver prices) are **immutable and append-only**. 
+  - System syncs rates to `CommodityRateHistory`.
+  - Rate synchronization NEVER overwrites the historical purchase cost or pre-calculated selling prices of individual `InventoryItem` records. Valuations are calculated dynamically at runtime when needed.
+- **Dynamic Valuation**: `InventoryValuationService` calculates real-time inventory value by multiplying available fine weight by the latest `CommodityRateHistory` rate, adding making charges, and rendering it instantly on the Business Dashboard via a riverpod provider.
 
 ### 3. Vendor & Purchase Orders
-- Active development on Vendor Management, Purchase Orders, and Purchase Payments. 
+- Purchase Orders map to Vendors.
+- Receiving a Purchase Order creates individual `InventoryItem` tags representing real physical stock (e.g. individual chains, rings) rather than simply bumping aggregate product stock totals.
 
-### 4. Project Management (Tasks)
+### 4. Customer & Sales/Invoice Module
+- **Invoice to Inventory Linking**: `InvoiceItem` records map directly to specific physical `InventoryItem` tags (`inventory_item_id`) rather than just master products.
+- **HUID Barcode Scanning**: The `InvoiceBuilderScreen` scans and prioritizes mapping directly to a unique HUID from `InventoryItem`. This natively prevents duplicating unique items in the same invoice. 
+- **Stock Deduction**: Finalizing an invoice or creating a non-draft invoice automatically marks the referenced `InventoryItem` records as `SOLD`.
+- Financial breakdown fields (`making_charge`, `other_charges`, `hsn_code`) are captured at the item level.
+
+### 5. Reporting & Audit Module
+- **Reports Hub**: Accessible from the Business Hub, features live tracking of Real-time Inventory Valuation.
+
+### 5. Project Management (Tasks)
 - Supports full Project creation, task assignment, and billing rates.
-- **Task Comments & Attachments**: Task comments support both legacy Base64 attachments (stored in PostgreSQL) and newer MinIO-backed attachments. Native downloading and sharing of non-image files (PDFs, Docs) is implemented via `file_picker` and `share_plus`. Images utilize a full-screen zoomable gallery.
+- **Task Comments & Attachments**: Task comments support both legacy Base64 attachments (stored in PostgreSQL) and newer MinIO-backed attachments.
 
-### 5. UI Standardization
+### 6. UI Standardization
 - **Design System**: The application strictly adheres to a uniform, enterprise-grade design system across all list screens (Projects, Invoices, Vendors, Task Board). 
-- **Standard Themes**: `Colors.grey[100]` is the standard background color, and search fields use white containers with rounded corners and no borders. The `CustomersScreen` serves as the UI source of truth.
+- **Material 3 / UI-UX Rules**: UI components avoid generic Material layouts, utilizing dynamic modern aesthetics, dynamic profile avatars, and proper padding/borders. 
+- **Standard Themes**: `Colors.grey[100]` is the standard background color, and search fields use white containers with rounded corners and no borders.
 
 ## Important Technical Rules & Conventions
-1. **R2DBC Limitations**: Because R2DBC is fully reactive, it does not automatically fetch relations (no lazy loading like Hibernate). Transient relational fields (e.g. `@Transient List<ProductImage> images` in `Product`) MUST be manually populated in the Service layers using `Mono.zip` or `flatMap` before returning to the controller.
-2. **API Routing (kifi vs kifi-v2)**: The application is migrating to a new reactive backend. New endpoints are mapped under `/api/kifi-v2/` (e.g., `/api/kifi-v2/inventory/products`), while some legacy mobile integrations might still point to `/api/kifi/` (e.g., transactions). Pay close attention to Base URL configurations in `DioClient` vs hardcoded URLs in UI widgets.
+1. **R2DBC Limitations**: Because R2DBC is fully reactive, it does not automatically fetch relations (no lazy loading). Transient relational fields MUST be manually populated in the Service layers using `Mono.zip` or `flatMap` before returning to the controller.
+2. **API Routing (kifi vs kifi-v2)**: The application is migrating to a new reactive backend. New endpoints are mapped under `/api/kifi-v2/`.
 3. **Payload Limits**: `spring.codec.max-in-memory-size` is set to `10MB` in `application.yml` to prevent `DataBufferLimitException` when handling large image uploads/downloads.
-4. **Image/Attachment Loading**: The backend reads byte buffers from MinIO (Base64) and decodes them to byte arrays (`byte[]`) to serve over HTTP. Flutter uses `Image.network` (or `NetworkImage`) with Bearer tokens in headers to fetch these secured endpoints.
+4. **Image/Attachment Loading**: The backend reads byte buffers from MinIO (Base64) and decodes them to byte arrays (`byte[]`) to serve over HTTP.