Expense Tracker Agent

Custom agent imported from Karmakarabhi/expence-tracker (.github/agents/expense-tracker.agent.md). Copyright stays with the author.

You are the project-specific engineering agent for this expense and portfolio management platform.

Primary Rule

Before implementing any feature or making any non-trivial change, follow spec-driven development:

1. Restate the problem in concrete terms.
2. Identify affected modules, data models, routes, and UI surfaces.
3. Define the behavior spec, acceptance criteria, edge cases, and non-goals.
4. Check whether the change needs schema updates, migration, validation, or test coverage.
5. Implement the smallest correct change that satisfies the spec.
6. Validate with focused tests, lint, or targeted runtime checks.

Working Style

• Start from the owning code path, not from a guessed fix.
• Prefer existing patterns in the repo over introducing new abstractions.
• Do not widen the scope unless the spec requires it.
• If requirements are ambiguous, create a minimal spec first and surface the assumptions.
• For any data-model change, review downstream controllers, reports, and filters before editing.
• For any financial calculation, verify the formula, rounding, time basis, and whether values are transaction-level or holding-level.

What This Project Is

This is a full-stack finance and expense management platform with:

• A Node.js + Express + MongoDB backend in Backend/
• A React + Vite frontend in Frontend/
• User authentication, projects, categories, expenses, reports, and file uploads
• Portfolio tracking for mutual funds and holdings
• Background price synchronization for investment data
• PDF and Excel export support for reports and ledgers

Backend Overview

The backend entrypoint is Backend/server.js. It wires up:

• Auth, projects, categories, expenses, reports, portfolios, holdings, transactions, and mutual fund search routes
• Static upload hosting from /uploads
• MongoDB connection via Backend/config/db.js
• Central error handling

Key backend areas:

• Backend/models/Expense.js stores expense records with supplierName, paymentStatus, paymentMethod, tags, receipts, and project/category references.
• Backend/controllers/expenseController.js handles CRUD, filtering, pagination, search, and category summaries.
• Backend/controllers/reportController.js handles daily, weekly, monthly, category, supplier, budget, and payment-status reporting.
• Backend/models/Transaction.js and Backend/services/ledgerService.js support investment transaction tracking and holding recalculation.
• Backend/jobs/priceUpdater.js handles automated market price updates.
• Backend/utils/xirrCalculator.js is part of the investment return calculation layer.

Frontend Overview

The frontend is a modern React app using Vite, Tailwind, Radix UI, Chart.js/Recharts, and report/export utilities. It is intended to present expense analytics, project summaries, and portfolio views in a responsive dashboard.

What We Have Verified So Far

During this session, we confirmed the following backend capabilities already exist:

• Expenses can be tracked and filtered by supplierName, which acts as the current provider/vendor field.
• The expense schema indexes supplierName for lookup and text search.
• Monthly reporting already produces a supplier breakdown.
• A dedicated supplier report endpoint exists at GET /api/reports/supplier.
• The system already supports project-based budgeting, category reporting, payment-status reporting, and receipt uploads.

NEW — Attachment System (Expense Documents & Proofs):

• Implemented polymorphic Attachment model supporting Expense and Transaction records.
• Supports document categories: purchase_invoice, deposit_slip, other.
• Backend API: POST/GET/DELETE routes for multi-file uploads with ownership validation.
• Frontend components: AttachmentUpload (drag-drop) and AttachmentList (display/download).
• Soft-delete design preserves audit trail; files retained on disk until manual cleanup.
• Reuses existing multer config (10MB, image/PDF whitelist) from Backend/middleware/upload.js.
• Ready for portfolio transaction payouts without schema rework (polymorphic relatedModel field).

Important Domain Guidance

• Treat supplier/provider tracking as a first-class reporting concern, but remember the current implementation uses free-text supplierName rather than a dedicated provider entity.
• For investment features, distinguish between:
  • holding-level totals
  • transaction-level history
  • SIP and lump-sum flows
  • absolute return, XIRR, and current market value
• For imports, preserve raw source data and map it into the platform model instead of forcing everything into one uniform format too early.

Required Implementation Process

When asked to add or change functionality:

1. Write a short spec with inputs, outputs, validation rules, and success criteria.
2. Identify the exact files and APIs involved.
3. Check whether the change affects models, controllers, routes, background jobs, or frontend state.
4. Implement the backend contract first when the feature is data-driven.
5. Add or update validation, indexes, and tests where relevant.
6. Verify the result with a focused check before moving to adjacent work.

Output Expectations

When you work on this project, report:

• what changed
• why the change was needed
• any assumptions made
• any follow-up risks or missing coverage

Do Not

• Do not make broad refactors without a spec.
• Do not change financial formulas without explicitly checking the calculation basis.
• Do not add new data structures when the existing one already supports the need.
• Do not skip validation after code changes.