Imported from wmaliffirdaus/finance-application (
AGENTS.md). Install upstream withnpx skills add wmaliffirdaus/finance-application. Copyright stays with the author.
AGENTS.md
Personal Finance Tracker — AI Project Instructions
Project Overview
Build a production-ready Personal Finance Tracker mobile application that provides a premium fintech experience similar to Money Manager, Wallet by BudgetBakers, Revolut, Monzo, and Spendee.
The application must be scalable, maintainable, secure, responsive, and suitable for publishing on both Google Play Store and Apple App Store.
Always prioritize code quality over speed.
Tech Stack
Mobile
- React Native (Latest Stable)
- TypeScript
- React Navigation
- React Query (TanStack Query)
- React Hook Form
- Zod Validation
- React Native Reanimated
- React Native Gesture Handler
- React Native SVG
- React Native Paper (Material Design 3)
- MMKV + Hive-style local repository for offline caching
- Secure Storage for JWT
- Expo Image Picker / Native Image Picker
- Expo Notifications / Firebase Cloud Messaging
- React Native Biometrics
Backend
Choose one:
Option A (Preferred)
- Django
- Django REST Framework
- PostgreSQL
- Redis
- Celery
- JWT Authentication
- SimpleJWT
Option B
- Flask
- SQLAlchemy
- PostgreSQL
- Alembic
- JWT
- Redis
- Celery
Architecture
Always follow:
- Clean Architecture
- MVVM
- Repository Pattern
- Dependency Injection
- SOLID Principles
- DRY
- KISS
- Feature-first folder structure
Never place business logic inside UI components.
Folder Structure
Example:
src/
features/
auth/
dashboard/
wallet/
transactions/
budgets/
reports/
profile/
settings/
core/
api/
storage/
network/
constants/
theme/
utils/
services/
shared/
components/
widgets/
hooks/
models/
Every feature must remain isolated.
Coding Standards
Always:
- Use TypeScript
- Strict typing
- Avoid "any"
- Small reusable components
- Small reusable hooks
- Proper comments only when necessary
- Meaningful naming
- Async/Await
- Error Boundaries
- Loading states
- Empty states
- Skeleton loading
- Pull-to-refresh
- Infinite scrolling
- Pagination
Never:
- Duplicate code
- Hardcode values
- Mix UI with API
- Mix API with database logic
State Management
Use:
- React Query for server state
- Context only for authentication/theme
- Local component state when appropriate
Avoid unnecessary global state.
Offline First
The application must support offline usage.
Requirements:
- Cache API responses
- Queue write operations
- Auto-sync when internet returns
- Resolve conflicts safely
- Retry failed requests
Authentication
Implement:
- JWT Authentication
- Refresh Token
- Secure Storage
- Auto Login
- Auto Refresh Token
- Logout
- Session expiration handling
Support:
- Email Login
- Google Login
- Apple Login (iOS)
Optional:
- Biometric Login
- Face ID
- Fingerprint
API Standards
Every endpoint must include:
- Validation
- Pagination
- Filtering
- Sorting
- Searching
- Authentication
- Proper HTTP Status Codes
Response format:
{
"success": true,
"message": "",
"data": {},
"pagination": {}
}Error format:
{
"success": false,
"message": "Readable error message"
}Database
Use PostgreSQL.
Tables:
- Users
- Wallets
- Transactions
- Categories
- Budgets
- SavingsGoals
- Notifications
- RecurringTransactions
- ReceiptImages
- Tags
Relationships must use proper foreign keys and indexes.
Never duplicate data.
Mobile Pages
Implement the following pages.
Authentication
- Splash
- Onboarding
- Login
- Register
- Forgot Password
- OTP Verification
- Reset Password
Dashboard
Display:
- Current Balance
- Monthly Income
- Monthly Expenses
- Remaining Budget
Charts:
- Spending Pie Chart
- Weekly Bar Chart
- Monthly Cash Flow Line Chart
Widgets:
- Budget Progress
- Savings Goal Progress
- Recent Transactions
Quick Actions:
- Add Income
- Add Expense
- Budget
- Transfer
Bottom Navigation
- Dashboard
- Transactions
- Budget
- Reports
- Profile
Transactions
Features:
- List
- Search
- Filter
- Sort
- Swipe Edit
- Swipe Delete
- Infinite Scroll
Tabs:
- All
- Income
- Expense
Add Transaction
Fields:
- Income / Expense
- Amount
- Category
- Wallet
- Date
- Time
- Notes
- Receipt
- Location
- Tags
Transaction Detail
Display:
- Amount
- Wallet
- Category
- Receipt
- Notes
Actions:
- Edit
- Delete
Wallets
Support multiple wallets:
- Cash
- Bank
- Credit Card
- Debit Card
- E-Wallet
CRUD required.
Categories
Income and Expense categories.
Support:
- CRUD
- Custom Color
- Custom Icon
Budget
Features:
- Monthly Budget
- Category Budget
- Budget Progress
- 80%
- 90%
- 100% Alerts
- History
Savings Goals
Fields:
- Goal Name
- Target
- Deadline
- Saved Amount
Include:
- Progress
- Contribution History
Reports
Charts:
- Pie
- Bar
- Line
Reports:
- Weekly
- Monthly
- Yearly
- Custom Range
Include financial summaries.
Calendar
Show:
- Transactions
- Daily Spending
Search
Search by:
- Category
- Merchant
- Notes
- Amount
- Date
- Tags
Recurring Transactions
Support:
- Daily
- Weekly
- Monthly
- Yearly
Examples:
- Salary
- Rent
- Bills
- Netflix
- Insurance
Auto-generate transactions.
Notifications
Include:
- Budget Warning
- Salary Reminder
- Savings Reminder
- Bills Reminder
Support Push Notifications.
Statistics
Display:
- Highest Spending Category
- Largest Expense
- Average Daily Spending
- Average Monthly Spending
- Total Income
- Total Expense
- Savings Rate
- Total Transactions
- Saving Streak
Export
Support:
- CSV
- Excel
Allow sharing.
Receipt Scanner
Features:
- Upload Receipt
- OCR
- Auto Detect
Extract:
- Merchant
- Amount
- Date
- Category
AI Insights (Optional)
Generate:
- Spending Analysis
- Saving Suggestions
- Monthly Comparison
- Financial Health Score
- Detect Unusual Spending
Profile
Editable:
- Avatar
- Name
- Phone
- Currency
- Language
- Timezone
Settings
Include:
- Light Mode
- Dark Mode
- Currency
- Language
- Notification Settings
- Backup
- Restore
- Export Data
- Delete Account
- Logout
Admin Dashboard (Web)
Build a responsive admin panel.
Features:
- User Management
- Categories
- Transactions
- Reports
- Dashboard Analytics
- User Statistics
Premium Features
Implement where possible:
- Offline Mode
- Auto Sync
- Secure Storage
- Multi Currency
- Exchange Rates
- Family Wallet
- QR Payment History
- Google Drive Backup
- Image Compression
- API Pagination
- Search Optimization
- Fingerprint Login
- Face ID
UI & UX Requirements
Design inspiration:
- Revolut
- Monzo
- Wallet by BudgetBakers
- Spendee
- Money Manager
Use:
- Material Design 3
- 8pt Grid System
- Rounded Corners (16–20px)
- Premium Cards
- Soft Shadows
- Smooth Animations
- Beautiful Typography
- Responsive Layout
- Tablet Support
Color Palette:
- Green → Income
- Red → Expense
- Orange → Budget
- Blue → Analytics
Support:
- Light Theme
- Dark Theme
Performance
Optimize for:
- Fast startup
- Lazy loading
- Code splitting
- Image caching
- Image compression
- API caching
- Efficient rendering
- FlatList optimization
- Memoization
Security
Implement:
- JWT
- Refresh Tokens
- Secure Storage
- HTTPS Only
- Input Validation
- SQL Injection Protection
- XSS Protection
- Rate Limiting
- Image Validation
- Authentication Middleware
Never expose secrets.
Testing
Include:
- Unit Tests
- Widget/Component Tests
- Integration Tests
- API Tests
Aim for high test coverage.
Deliverables
The final project should include:
- Production-ready mobile application
- Clean Architecture
- Well-organized source code
- Complete backend API
- PostgreSQL database
- Authentication
- Offline-first support
- Responsive UI
- Professional animations
- Error handling
- Loading states
- Empty states
- Documentation
- Environment configuration
- README
The final application should be indistinguishable from a commercial fintech application and be ready for deployment to the Google Play Store and Apple App Store.
