Kifi/prompt.md

You are a senior software architect, Flutter/mobile engineer, and Spring Boot/Java backend engineer with 10+ years of production experience.

You are working on an EXISTING application repository.

Your job is to transform the existing application into a modern, platform-independent PERSONAL FINANCE MANAGEMENT application while preserving and reusing as much existing functionality as possible.

IMPORTANT: Do NOT rebuild the application from scratch. Do NOT replace working functionality simply because you prefer another architecture. Do NOT introduce a new framework/state-management/library without first checking what the project already uses. Do NOT make destructive database changes. Do NOT remove existing features unless explicitly required.

============================================================ PRIMARY PRODUCT GOAL

Transform the existing application into a personal finance/accounting management app for ordinary users.

The user should be able to:

• track income
• track expenses
• manage cash
• manage bank accounts
• manage savings
• manage investments
• track loans
• track money lent to others
• transfer money between wallets
• create budgets
• analyze spending
• view financial history
• attach receipts/documents/images
• share wallets with other users

The application must be understandable to users who know nothing about accounting.

Avoid accounting terminology in the UI where possible.

Use friendly terminology such as:

"Wallet" "Money In" "Money Out" "Transfer" "Savings" "Investment" "Money Lent" "Loan" "Balance"

Internal technical/accounting terminology may remain different if necessary.

============================================================ PHASE 0 — INSPECT BEFORE CODING

FIRST inspect the entire repository.

Do NOT start making large changes immediately.

Understand:

1. Flutter architecture
2. Flutter state management
3. Flutter navigation
4. Existing screens
5. Existing widgets/components
6. Existing models
7. Existing API layer
8. Existing authentication
9. Existing transaction workflow
10. Existing account/wallet implementation
11. Existing category implementation
12. Existing items implementation
13. Existing attachment/image upload implementation
14. Existing wallet-sharing implementation
15. Spring Boot architecture
16. Controllers
17. Services
18. Repositories
19. DTOs
20. Entities
21. Database schema
22. Database migrations
23. Configuration
24. Security/authorization
25. Existing tests

Search the repository instead of guessing.

Identify what can be reused.

Identify broken functionality.

Identify technical debt that directly affects this transformation.

Then produce a concise report:

• Current architecture
• Current application workflow
• Current data model
• Current transaction model
• Existing reusable functionality
• Existing broken functionality
• Attachment implementation
• Wallet sharing implementation
• Risks
• Recommended implementation order

Only after this analysis begin implementation.

============================================================ PRODUCT REQUIREMENT

The client wants to change the nature of the application.

Current application workflow is too limited.

New application:

PERSONAL FINANCE MANAGEMENT

============================================================

1. WALLETS ============================================================

Use "Wallet" as the primary user-facing concept instead of "Account" if this fits the existing architecture.

A wallet represents a place/type where money is tracked.

Examples:

Cash Bank Account Credit Card Savings Investment Loan Money Lent Salary Other

Users can create custom wallets.

However, the system must control the underlying financial nature/type.

Separate:

USER-FACING WALLET from SYSTEM FINANCIAL NATURE

Suggested internal nature values:

EXPENSE INCOME CASH DEPOSIT SAVINGS INVESTMENT LOAN LEND TRANSFER

You may improve this model if repository analysis indicates a better normalized design.

The user should not be able to create arbitrary financial natures.

Each wallet should support where applicable:

• id
• name
• icon
• customizable icon
• color/theme
• nature/type
• opening balance
• current balance
• currency
• description
• active/archived
• createdAt
• updatedAt

Prefer ARCHIVE over DELETE when transactions already reference a wallet.

Do not destroy historical financial data.

============================================================ 2. TRANSACTIONS

The primary "+" action should be extremely simple.

When the user taps "+":

Step 1: Amount

Step 2: From Wallet

Step 3: To Wallet

Then:

• Category
• Description
• Items
• Attachments
• Date/time
• Notes

Negative transaction amounts must be supported.

Examples:

Expense: Bank → Food/Expense

Income: Income → Bank

Transfer: Bank → Cash

Savings: Bank → Savings

Investment: Bank → Investment

Money lent: Bank → Money Lent

Loan received: Loan → Bank

The UI should explain From/To in simple language.

Example:

"From Wallet" Where the money comes from.

"To Wallet" Where the money goes.

Do not force users to understand debit/credit terminology.

============================================================ 3. TRANSACTION EDITING

Users must be able to edit:

• amount
• from wallet
• to wallet
• category
• description
• items
• attachments
• date/time
• notes

After editing:

• balances must be recalculated correctly
• reports must remain correct
• dashboard totals must remain correct
• ledger must remain correct

Support:

• edit
• delete/cancel
• attachment add/remove/replace
• item add/edit/remove

Use confirmation for destructive operations.

============================================================ 4. ATTACHMENTS

The existing image upload is currently not working.

FIX THE ROOT CAUSE.

Inspect the entire pipeline:

Flutter → request/multipart → Spring Boot → storage → database/reference → retrieval → Flutter display

Do not hide the error.

Support where practical:

• camera
• gallery
• file picker
• image preview
• multiple attachments
• upload progress
• retry
• delete
• replace
• error state

Preserve existing attachment data.

============================================================ 5. WALLET SHARING

Existing wallet-sharing functionality MUST remain.

Do not remove it.

Inspect the existing implementation first.

Preserve existing behavior.

Improve UX if useful.

Potential permissions:

OWNER VIEW EDIT

Authorization must be enforced on the backend.

Never rely only on Flutter UI restrictions.

============================================================ 6. DASHBOARD

Build a rich financial dashboard.

Include:

• total balance / net position
• income
• expenses
• savings
• investments
• loans
• money lent
• cash
• recent transactions
• budget status
• spending trends
• wallet summaries

Provide nature-based tabs/cards such as:

All Cash Spending Savings Investments Loans Money Lent

Each card should show:

• current balance
• trend
• relevant summary
• icon
• visual indicator

Cards must be tappable.

Tap a card → detailed ledger.

============================================================ 7. LEDGER

Dashboard cards and wallets should open a ledger-style transaction view.

Conceptually show:

Date | Amount | From | To | Balance

On mobile use responsive cards/list rows rather than literal desktop tables.

Each transaction should show:

• date/time
• amount
• from wallet
• to wallet
• category
• description
• attachment indicator
• item count
• running balance

Support:

• search
• date range
• wallet filter
• nature filter
• category filter
• amount range
• income/expense filter
• attachment filter
• sorting
• ascending/descending
• pagination/infinite scrolling

============================================================ 8. CATEGORIES

Preserve existing categories.

Improve where appropriate.

Examples:

Food Transport Shopping Bills Health Education Entertainment Salary Freelance Investment Loan Other

Allow user management where safe:

• create
• rename
• archive
• icon
• color

Do not break existing category records.

============================================================ 9. ITEMS

Preserve existing transaction item functionality.

Example:

Grocery ₹1,250

Rice ₹500 Vegetables ₹300 Snacks ₹250 Other ₹200

Display:

• item name
• quantity if supported
• price
• total

Transaction total should be validated against item totals where appropriate.

============================================================ 10. BUDGETING

Add budgeting functionality.

Support:

• monthly budgets
• category budgets
• wallet-specific budgets

Show:

Allocated Spent Remaining Percentage used

Provide warning levels.

Examples:

70% → informational 90% → warning 100%+ → exceeded

Make thresholds configurable if appropriate.

============================================================ 11. REPORTS / ANALYTICS

Provide understandable financial analytics.

Charts:

• income vs expenses
• spending by category
• cash flow
• savings trend
• investment trend
• wallet distribution
• top spending categories
• monthly comparison
• recurring expenses

Charts must be mobile friendly.

Avoid excessive complexity.

============================================================ 12. SEARCH / FILTER

Provide powerful transaction filtering.

Filters:

• date
• wallet
• category
• nature
• amount
• income/expense
• attachment
• item
• text search

Make filtering easy for non-technical users.

============================================================ 13. RECURRING TRANSACTIONS

If compatible with the existing architecture, support:

• salary
• rent
• EMI
• subscriptions
• insurance
• SIP
• recurring bills

Fields:

• frequency
• start date
• end date
• next occurrence
• active/inactive

Do not over-engineer this if it conflicts heavily with the current architecture.

============================================================ 14. ALERTS / NOTIFICATIONS

Useful alerts:

• budget nearing limit
• budget exceeded
• upcoming recurring payment
• loan due
• lending due
• unusual spending
• failed upload
• wallet activity

Allow notification preferences.

============================================================ 15. USER EDUCATION

The application must teach users how to use it.

Provide:

• onboarding
• contextual hints
• tooltips
• "What is this?" explanations
• guided tours
• contextual help
• examples

Example:

"From Wallet" Where the money comes from.

"To Wallet" Where the money goes.

"Nature" How the app categorizes this money movement.

Users should be able to:

• skip
• replay
• disable hints

Do not make onboarding annoying.

============================================================ 16. UI / UX

Create a polished modern financial application.

Requirements:

• modern Flutter UI
• responsive design
• light theme
• dark theme
• customizable icons
• meaningful icons
• smooth animations
• animated dashboard cards
• page transitions
• bottom sheets
• dialogs
• snackbars
• loading states
• skeleton loaders
• empty states
• error states
• confirmation dialogs
• pull-to-refresh
• swipe actions where appropriate
• floating Add button

Suggested navigation:

Dashboard Wallets Transactions Budgets Reports Profile

BUT:

Do not force this navigation if the existing application's navigation architecture is better.

Reuse existing navigation where practical.

============================================================ 17. PROFILE / SECURITY

Preserve existing authentication.

Improve where appropriate.

Possible features:

• profile
• password/security
• PIN
• biometric lock
• logout
• notification settings
• currency
• theme
• privacy
• data export
• account deletion

Never expose another user's financial information.

============================================================ 18. FINANCIAL DATA MODEL

This is CRITICAL.

Design a consistent transaction model.

Every transaction should have:

• id
• user/owner context
• amount
• fromWallet
• toWallet
• timestamp
• category
• description
• items
• attachments
• metadata

Wallet balance must be deterministic.

Avoid duplicated balance calculations.

Do not use floating point for money.

Backend: Use Java BigDecimal.

Flutter: Use a safe monetary representation appropriate for the existing architecture.

Use database transactions for financial operations.

Ensure edits/deletes correctly update financial calculations.

============================================================ 19. NEGATIVE AMOUNTS

Negative values are explicitly allowed.

Define and document exactly how negative transactions affect:

• from wallet
• to wallet
• wallet balance
• income
• expense
• reports
• budgets

Do not let different parts of the application interpret negative amounts differently.

The backend is the source of truth.

============================================================ 20. BACKEND

Inspect the existing Spring Boot architecture first.

Reuse:

• controllers
• services
• repositories
• DTOs
• entities
• authentication
• exception handling
• migrations

Extend existing APIs rather than creating duplicates.

Use:

• DTO validation
• service-layer business logic
• transaction boundaries
• authorization
• consistent API errors

Financial business rules belong on the backend.

Never rely exclusively on Flutter validation.

============================================================ 21. DATABASE

Before modifying entities:

1. Understand existing schema.
2. Understand existing data.
3. Preserve existing records.
4. Create migrations.
5. Avoid destructive migrations.
6. Provide defaults for old records.
7. Maintain backward compatibility where practical.

Never silently delete user financial data.

============================================================ 22. FLUTTER ARCHITECTURE

Inspect the current Flutter architecture first.

Preserve existing:

• state management
• routing
• API client
• repository pattern
• dependency injection
• theme
• widgets

Do NOT replace state management just because another solution is preferred.

Create reusable:

• wallet widgets
• transaction widgets
• dashboard cards
• ledger rows
• filters
• forms
• dialogs
• charts
• attachment components

Maintain iOS/Android parity.

============================================================ 23. TESTING

Backend tests:

• unit tests
• service tests
• controller tests
• authorization tests
• transaction tests
• balance tests

Flutter tests:

• widget tests
• transaction form tests
• wallet tests
• balance tests
• dashboard tests
• attachment tests

Critical scenarios:

1. Create wallet
2. Create income
3. Create expense
4. Transfer money
5. Negative transaction
6. Edit transaction
7. Delete transaction
8. Upload attachment
9. Replace attachment
10. Shared wallet
11. Budget calculation
12. Dashboard totals
13. Ledger running balance
14. Unauthorized wallet access

============================================================ 24. PERFORMANCE

The application should remain responsive with large transaction histories.

Consider:

• pagination
• lazy loading
• database indexes
• optimized queries
• cached dashboard summaries
• debounced search
• image compression
• thumbnail generation
• background upload
• efficient chart data

Do not optimize prematurely.

Measure first where possible.

============================================================ 25. ACCESSIBILITY

Support:

• readable typography
• sufficient contrast
• semantic labels
• screen-reader friendly controls
• touch-friendly controls
• scalable text where practical

Do not rely only on color to communicate financial status.

============================================================ 26. IMPLEMENTATION PHASES

Do NOT implement everything in one giant change.

PHASE 1: Repository analysis Architecture understanding Data model analysis Existing functionality inventory Implementation plan

PHASE 2: Wallet/account model Transaction model Balance calculation Create/edit transaction

PHASE 3: Dashboard Ledger Search Filters

PHASE 4: Attachments Items Categories Wallet sharing

PHASE 5: Budgets Reports Analytics Recurring transactions

PHASE 6: Notifications Onboarding Guided tours Profile/security

PHASE 7: UI polish Animations Accessibility Performance Testing iOS/Android validation

After every phase:

• build backend
• run backend tests
• run Flutter analyzer
• run Flutter tests
• fix compilation errors
• fix test failures
• verify affected functionality

============================================================ 27. CODE QUALITY RULES

Follow existing project conventions.

Prefer small, maintainable changes.

Avoid unnecessary abstractions.

Avoid duplicate models/services.

Avoid dead code.

Avoid magic constants.

Use meaningful names.

Document complicated financial business rules.

Do not hide errors.

Do not suppress compiler warnings simply to make builds pass.

Do not disable tests.

Do not remove tests to make the implementation pass.

============================================================ 28. GIT / CHANGE SAFETY

Before major modifications:

Inspect git status.

Do not overwrite unrelated user changes.

Do not reset/revert user work.

Do not delete files unless you have established they are obsolete.

Keep changes logically grouped.

============================================================ 29. IMPORTANT AGENT BEHAVIOR

When uncertain:

1. Inspect the code.
2. Search for existing implementation.
3. Follow existing conventions.
4. Make the smallest safe change.

Do not guess the architecture.

Do not assume an API exists.

Do not create duplicate functionality.

Do not rewrite working modules unnecessarily.

If a requirement conflicts with existing behavior, explain the conflict before making a destructive architectural change.

============================================================ 30. FIRST RESPONSE / FIRST ACTION

DO NOT IMPLEMENT FEATURES YET.

First inspect the repository.

Then report:

A. Current architecture B. Flutter architecture C. Spring Boot architecture D. Current database model E. Current account/wallet model F. Current transaction workflow G. Current dashboard H. Current attachment implementation I. Current wallet sharing implementation J. Existing reusable functionality K. Existing bugs/problems L. Proposed target architecture M. Database migration strategy N. API changes required O. Flutter screens/components required P. Implementation phases

Then begin PHASE 1.

Do not proceed with a massive rewrite.

Implement incrementally and verify every phase.