60 lines
5.1 KiB
Markdown
60 lines
5.1 KiB
Markdown
# 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.
|