z33xd/finance-tracker

Purpose and Entry Points

Finance Tracker is a personal-finance system with a Spring Boot REST API and React/Vite client. The backend starts at src/main/java/com/fintrack/finance_tracker/FinanceTrackerApplication.java; the browser client starts at frontend/src/main.jsx and routes from frontend/src/App.jsx. The API manages authenticated users’ accounts, ledger transactions, categories, budgets, CSV imports, and currency reporting.

Client Application

The React SPA presents dashboard, account, transaction, budget, category, profile, and authentication views. frontend/src/context/AuthContext.jsx owns client authentication state; frontend/src/components/ProtectedRoute.jsx gates secured views. frontend/src/services/api.js is the HTTP boundary to the backend, while frontend/src/components/Navbar.jsx provides authenticated navigation. The production frontend is containerized and served through Nginx (frontend/Dockerfile, frontend/nginx.conf).

API and Domain Boundary

Backend domains follow a controller → service → Spring Data JPA repository/entity structure. Controllers expose REST endpoints, services implement user-scoped business rules and ledger effects, and repositories persist relational records to PostgreSQL. Core financial resources are:

• Accounts and dashboard summaries: accounts/AccountController.java, accounts/AccountService.java, accounts/AccountSummary.java

• Transactions, the primary ledger: transactions/TransactionController.java, transactions/TransactionService.java, transactions/Transaction.java

• Category-based spending caps: budgets/BudgetService.java, budgets/BudgetSummary.java, categories/Category.java

Authentication and Data Isolation

Public registration, login, and verification flow through authentication/AuthenticationController.java and authentication/AuthenticationService.java. JWT issuance and validation are separated into jwt/JwtService.java and config/JwtAuthenticationFilter.java; config/SecurityConfiguration.java applies stateless Spring Security. The authenticated principal is the isolation boundary: financial controllers/services scope operations to the current user rather than accepting an unrestricted tenant context. Signup verification uses email/EmailService.java with mail configuration in config/EmailConfiguration.java.

Financial Reporting and Exchange Rates

Amounts remain native to account/budget currencies. Read-time summaries convert balances or spending using persisted date-specific exchange-rate pairs. exchange_rates/ExchangeRateService.java manages retrieval/cache behavior, exchange_rates/CurrencyConversionService.java performs conversions, and exchange_rates/BaseCurrencyResolver.java determines the reporting anchor from the user’s first account. The external ExchangeRate-API is accessed through Spring’s configured web client (config/WebClientConfig.java) and requires an API key.

CSV Import Pipeline

Bulk uploads enter at import_batches/ImportBatchController.java and are staged/audited as ImportBatch records. import_batches/ImportBatchService.java parses and validates rows, detects duplicates, records job totals/status, and creates accepted ledger entries through the transaction path. This boundary protects account balance consistency while preserving batch-level processing telemetry; transactions/TransactionRepository.java and import_batches/ImportBatchRepository.java support the persistence side.

Runtime and Infrastructure

The backend is Java 21, Spring Boot 3, Maven, Spring Security, JPA/Hibernate, and PostgreSQL (pom.xml, src/main/resources/application.properties). Docker packaging exists for both application tiers (Dockerfile, frontend/Dockerfile) and orchestration is defined in docker-compose.yml. Required external dependencies are PostgreSQL, an SMTP/mail provider for verification, and ExchangeRate-API.