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.

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.
  • Example: Interest/bank fees on a Credit Card are recorded as a transfer: From: CC -> To: Expense (Bank Charges/Interest).
• 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.

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.

3. Vendor & Purchase Orders

• Active development on Vendor Management, Purchase Orders, and Purchase Payments.

4. 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.

5. 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.

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.
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.