# Kifi Project Handoff Document

This document provides an overview of the Kifi project, detailing the architecture, recent implementations, current state, and instructions for running the application.

## 1. Project Overview & Architecture

Kifi is an enterprise-grade project management and CRM application consisting of a mobile frontend and a reactive backend.

### **Backend (`kifi-api`)**
- **Framework:** Spring Boot 3 with WebFlux (Reactive Stack)
- **Language:** Java 21
- **Database:** PostgreSQL accessed via Spring Data R2DBC
- **Caching & Sessions:** Redis (Reactive)
- **Security:** Spring Security with JJWT for token-based authentication
- **Storage:** Minio for S3-compatible object storage
- **Architecture Pattern:** Standard N-Tier (Controller → Service → Repository → Entity/DTO)

### **Frontend (`kifi-app`)**
- **Framework:** Flutter
- **State Management:** Riverpod
- **Networking:** Dio for HTTP requests
- **Key Dependencies:** `file_picker`, `image_picker`, `path_provider`, `share_plus`, `fl_chart`
- **Architecture Pattern:** Feature-first modular structure (`auth`, `projects`, `transactions`, `business`, etc.) with separation of `data`, `domain`, `presentation`, and `providers`.

---

## 2. Recent Major Implementations

### **UI Standardization & Enterprise Polish**
- **Objective:** Strictly adhere to a uniform, enterprise-grade design system across all list screens (Projects, Invoices, Vendors, Task Board), using the `CustomersScreen` as the source of truth.
- **Changes made:**
  - Standardized background colors to `Colors.grey[100]` across the app.
  - Implemented uniform search fields: white container, `grey[100]` fill, rounded corners, no borders.
  - Redesigned the `TaskCard` and task columns in the `ProjectBoardScreen` to look modern and functional.

### **Task Comments & File Attachments**
- **Initial State:** Task comments only supported base64 encoded images stored directly in the PostgreSQL `TEXT` column.
- **New Feature:** Implemented file attachments (PDFs, Docs, Images) for task comments with native downloading and sharing.
- **Backend Refactor:**
  - Integrated `MinioServiceClient` into `ProjectService`.
  - Modified `addComment` to intercept incoming base64 payloads, upload them to Minio in parallel using reactive streams (`Flux`), and save a JSON metadata string (`[{"fileName": "...", "contentType": "...", "filePath": "..."}]`) into the database.
  - Added a generic file download endpoint: `GET /projects/tasks/attachments/download`.
- **Frontend Refactor:**
  - Added `file_picker` dependency to support non-image documents.
  - Rebuilt the attachment picking UI in `TaskDetailsSheet` to support both images and generic files.
  - Implemented a secure download mechanism using `dio`, `path_provider`, and `share_plus` to save and open documents natively.
  - Added an interactive image gallery (`AttachmentGalleryScreen`) for previewing image attachments (both legacy base64 and new Minio-backed URLs).

---

## 3. Current State & Known Behaviors

- **Backward Compatibility:** The backend and frontend correctly handle "legacy" task comments that were saved purely as Base64 strings, alongside the new Minio-backed JSON structure.
- **Application Configuration:**
  - Max in-memory size for Spring WebFlux was increased to `10MB` in `application.yml` to allow for large base64-encoded file uploads before they are dispatched to Minio.
- **Outstanding Items:**
  - Since background services were interrupted, you may need to ensure your Minio container and Redis instance are up and running before testing the new upload flow.

---

## 4. Setup & Running Instructions

### **Backend**
1. Navigate to the backend directory:
   ```bash
   cd kifi-api
   ```
2. Ensure your local PostgreSQL, Redis, and Minio instances are running.
3. Clean and run the Spring Boot application:
   ```bash
   ./mvnw clean spring-boot:run
   ```

### **Frontend**
1. Navigate to the app directory:
   ```bash
   cd kifi-app
   ```
2. Fetch new dependencies (especially the newly added `file_picker`):
   ```bash
   flutter pub get
   ```
3. Run the app on your emulator or connected device:
   ```bash
   flutter run
   ```

> [!WARNING]
> Because new native dependencies (`file_picker`, `share_plus`) were added during the last session, hot-reloading will not work for these changes. **You must stop the Flutter application completely and perform a full `flutter run`** to compile the native platform channels.