{"id":28170605,"url":"https://github.com/nickklos10/finance-tracker-backend","last_synced_at":"2026-04-02T02:50:59.428Z","repository":{"id":291655689,"uuid":"977750732","full_name":"nickklos10/Finance-Tracker-backend","owner":"nickklos10","description":"Finance Tracker API is a Spring Boot application that provides a secure and scalable RESTful interface for managing personal finance data.","archived":false,"fork":false,"pushed_at":"2025-05-30T01:49:08.000Z","size":591,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-30T02:39:16.629Z","etag":null,"topics":["auth0","docker","postgresql","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickklos10.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-04T22:10:13.000Z","updated_at":"2025-05-30T01:49:11.000Z","dependencies_parsed_at":"2025-05-05T21:47:26.559Z","dependency_job_id":"e147a45f-2475-4799-9e44-4ad34f6c7b2c","html_url":"https://github.com/nickklos10/Finance-Tracker-backend","commit_stats":null,"previous_names":["nickklos10/ai-finance-tracker","nickklos10/finance-tracker-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nickklos10/Finance-Tracker-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickklos10%2FFinance-Tracker-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickklos10%2FFinance-Tracker-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickklos10%2FFinance-Tracker-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickklos10%2FFinance-Tracker-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickklos10","download_url":"https://codeload.github.com/nickklos10/Finance-Tracker-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickklos10%2FFinance-Tracker-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010343,"owners_count":26084738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth0","docker","postgresql","spring-boot"],"created_at":"2025-05-15T18:14:24.709Z","updated_at":"2025-10-12T05:06:18.912Z","avatar_url":"https://github.com/nickklos10.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Finance Tracker API (Backend)\n\n## Overview\n\nThe Finance Tracker API is a Spring Boot application that provides a secure and scalable RESTful interface for managing personal finance data. It supports CRUD operations for transactions and categories, user profile management, and integrates with Auth0 for authentication and authorization.\n\n## App Architecture\n\n\u003cimg width=\"1119\" alt=\"Screenshot 2025-05-30 at 7 37 54 PM\" src=\"https://github.com/user-attachments/assets/968cf606-5277-4aab-9aa4-3dfab173af16\" /\u003e\n\n\n## Table of Contents\n\n- [Features](#features)\n- [Technology Stack](#technology-stack)\n- [Prerequisites](#prerequisites)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n- [API Endpoints](#api-endpoints)\n  - [Transactions](#transactions)\n  - [Categories](#categories)\n  - [User Profile](#user-profile)\n- [Data Model](#data-model)\n- [Security](#security)\n- [Database Migrations](#database-migrations)\n- [Caching](#caching)\n- [Exception Handling](#exception-handling)\n- [Actuator](#actuator)\n- [Future Enhancements](#future-enhancements)\n\n## Features\n\n- CRUD operations for transactions and categories\n- Pagination and filtering (by type, date range, category)\n- User profile management (fetch, update, delete)\n- Secure endpoints with JWT (Auth0) and scope-based authorization\n- Method-level security and ownership checks\n- Global exception handling with RFC-7807 Problem Details\n- Flyway-based database migrations and seed data\n- Spring Cache for categories\n- Actuator endpoints for health and metrics\n\n## Technology Stack\n\n- Java 21\n- Spring Boot 3.4.x\n- Spring Security OAuth2 Resource Server (JWT)\n- Spring Data JPA (Hibernate)\n- PostgreSQL (via Docker Compose)\n- Flyway for migrations\n- Lombok for boilerplate reduction\n- Spring Cache\n- Spring Boot Actuator\n- Maven for dependency management\n\n## Prerequisites\n\n- Java 21 or higher\n- Maven 3.8 or higher\n- Docker \u0026 Docker Compose\n\n## Getting Started\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/your-org/finance-tracker-api.git\n   cd finance-tracker-api/backend\n   ```\n\n2. **Configure environment variables**\n\n   ```bash\n   export POSTGRES_USER=finance_user\n   export POSTGRES_PASSWORD=strong_password\n   export POSTGRES_DB=finance_db\n   export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/${POSTGRES_DB}\n   export SPRING_DATASOURCE_USERNAME=${POSTGRES_USER}\n   export SPRING_DATASOURCE_PASSWORD=${POSTGRES_PASSWORD}\n   ```\n\n3. **Start the PostgreSQL database**\n\n   ```bash\n   docker compose up -d\n   ```\n\n4. **Build and run the application**\n\n   ```bash\n   mvn clean install\n   mvn spring-boot:run -Dspring-boot.run.profiles=dev\n   ```\n\n5. **Access the API**\n   - Base URL: `http://localhost:8080/api`\n   - H2 Console: (not enabled by default)\n\n## Configuration\n\nConfiguration files are located in `src/main/resources`:\n\n- `application.properties`: base settings (application name, port, JPA SQL logging)\n- `application-dev.yml`: development profile (Actuator exposure, Flyway, security settings)\n\n### Environment Variables\n\n| Variable                     | Description               |\n| ---------------------------- | ------------------------- |\n| `POSTGRES_USER`              | PostgreSQL username       |\n| `POSTGRES_PASSWORD`          | PostgreSQL password       |\n| `POSTGRES_DB`                | PostgreSQL database name  |\n| `SPRING_DATASOURCE_URL`      | JDBC URL for the database |\n| `SPRING_DATASOURCE_USERNAME` | Database username         |\n| `SPRING_DATASOURCE_PASSWORD` | Database password         |\n\nAuthentication settings (issuer, audience) are currently hard-coded in `SecurityConfig` but can be externalized if needed.\n\n## API Endpoints\n\n### Transactions\n\n- `GET /api/transactions`  \n  Returns a paginated list of all transactions belonging to the authenticated user.\n- `GET /api/transactions/{id}`  \n  Fetch a single transaction by its ID.\n- `GET /api/transactions/type/{type}`  \n  Fetch transactions by type (`INCOME`, `EXPENSE`, `TRANSFER`).\n- `GET /api/transactions/date-range?startDate={ISO_DATE_TIME}\u0026endDate={ISO_DATE_TIME}`  \n  Fetch transactions between two dates (inclusive).\n- `GET /api/transactions/category/{categoryId}`  \n  Fetch transactions for a specific category.\n- `POST /api/transactions`  \n  Create a new transaction.  \n  Request body: `TransactionDTO`.\n- `PUT /api/transactions/{id}`  \n  Update an existing transaction.  \n  Request body: `TransactionDTO`.\n- `DELETE /api/transactions/{id}`  \n  Delete a transaction by ID.\n\n### Categories\n\n- `GET /api/categories`  \n  Returns a paginated list of all categories.\n- `GET /api/categories/{id}`  \n  Fetch a category by its ID.\n- `GET /api/categories/name/{name}`  \n  Fetch a category by its name.\n- `POST /api/categories`  \n  Create a new category.  \n  Request body: `CategoryDTO`.\n- `PUT /api/categories/{id}`  \n  Update an existing category.  \n  Request body: `CategoryDTO`.\n- `DELETE /api/categories/{id}`  \n  Delete a category by ID.\n\n### User Profile\n\n- `GET /api/users/me`  \n  Fetch the authenticated user's profile.\n- `PUT /api/users/me`  \n  Update the authenticated user's profile.  \n  Request body: `UserDTO`.\n- `DELETE /api/users/me`  \n  Delete the authenticated user's account.\n\n## Data Model\n\n### Entities\n\n- **AppUser**  \n  Stores users with fields: `id`, `auth0Sub`, `name`, `email`.\n- **Category**  \n  Stores spending categories: `id`, `name`, `description`.\n- **Transaction**  \n  Stores transactions: `id`, `description`, `amount`, `date`, `type`, `notes`, `category`, `user`.\n\n### DTOs\n\n- **UserDTO**: `id`, `auth0Sub`, `name`, `email`.\n- **CategoryDTO**: `id`, `name`, `description`.\n- **TransactionDTO**: `id`, `description`, `amount`, `date`, `type`, `categoryId`, `categoryName`, `notes`.\n\n## Security\n\n- **Auth0 Integration**: Validates JWT access tokens issued by Auth0.\n- **Scopes**: Requires scope `fin:app` to access API endpoints.\n- **Method Security**: Uses `@PreAuthorize` annotations and a custom `OwnershipEvaluator` bean to enforce resource ownership.\n- **CORS**: Configured to allow requests from `https://app.finsight.com`.\n- **HTTP Security Headers**: Content Security Policy, HSTS, Referrer Policy.\n\n## Database Migrations\n\nFlyway migrations are stored in `src/main/resources/db/migration`:\n\n- `V1__init.sql`: Creates tables (`users`, `categories`, `transactions`) and indexes.\n- `R__seed_categories.sql`: Inserts initial category data.\n\n## Caching\n\nCategories endpoints are cached using Spring Cache (cache name: `categories`). Cache is evicted on create/update/delete operations.\n\n## Exception Handling\n\nA global exception handler (`GlobalExceptionHandler`) returns standardized RFC-7807 Problem Details with fields:\n\n- `type`: URI identifying error type\n- `title`: HTTP status reason phrase\n- `status`: HTTP status code\n- `detail`: error message\n- `timestamp`: error occurrence time\n- `errors` (for validation failures): field-level error details\n\n## Actuator\n\n- `GET /actuator/health`: Public health check.\n- `GET /actuator/metrics`: Requires `fin:app` scope.\n\n## Future Enhancements\n\n- Externalize Auth0 configuration via environment variables\n- Rate limiting using Bucket4j (dependency included)\n- Role-based access control and custom permissions\n- Advanced reporting and analytics endpoints\n- Frontend application and mobile clients\n- AI-driven spending analysis and recommendations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickklos10%2Ffinance-tracker-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickklos10%2Ffinance-tracker-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickklos10%2Ffinance-tracker-backend/lists"}