# 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. It supports a specialized "Jewellery Business Mode".

### Components
- **kifi-app**: Flutter mobile frontend.
- **kifi-api**: Spring Boot WebFlux backend (reactive stack).
- **Infrastructure**: PostgreSQL database (accessed via R2DBC), MinIO for object storage (images/attachments), Redis, Docker registry (`hub.technobeesolutions.in`).

## Core Features & Architecture

### 1. Accounting System
- **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).
- **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. 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
- 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. 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.

### 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). 
- **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). 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.