Kifi/kifi_context.md

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.