How aditya9u/expense-tracker-backend works
1. This is a single-module Spring Boot backend for expense tracking, organized as a classic layered REST API. The codebase is centered in com.example.expense_tracker and is split into controller, service, repository, entity, DTO, and exception packages.
2. The top-level runtime entrypoint is ExpenseTrackerApplication, which boots the Spring container and wires the application context. There is no separate frontend or worker service in this repo; all business interaction appears to happen through HTTP APIs.
3. The API layer consists of three controllers: UserController, CategoryController, and ExpenseController. These are the boundary between external clients and the application, handling request/response shapes and delegating business logic downward.
4. Business logic lives in UserService, CategoryService, and ExpenseService. This is where CRUD behavior, validation-dependent rules, filtering/search/pagination behavior mentioned in the README, and cross-entity checks are expected to live.
5. Persistence is handled through Spring Data JPA repositories: UserRepository, CategoryRepository, and ExpenseRepository. These repositories form the data-access boundary to MySQL and likely use entity-based queries plus derived query methods for filtering and search.
6. The domain model is made up of three JPA entities: User, Category, and Expense. The README shows the core relationship as User 1..* Expense and Category 1..* Expense, so expense records are the central fact table connecting users and categories.
7. DTOs are used to separate external API contracts from persistence models. Request DTOs include CreateUserRequest, CategoryRequest, CreateExpenseRequest, and ExpenseRequest; response DTOs include UserResponse, CategoryResponse, ExpenseResponse, plus ErrorResponse for standardized error output.
8. Exception handling is centralized. Domain-specific exceptions such as UserNotFoundException, CategoryNotFoundException, ExpenseNotFoundException, and EmailAlreadyExistsException are translated by GlobalExceptionHandler into structured API errors instead of leaking framework exceptions to clients.
9. Validation is part of the API contract and is applied at the DTO boundary, which means invalid input is rejected before it reaches the service or repository layers. That keeps the service layer focused on business rules rather than basic request sanitation.
10. The application is configured for environment-based deployment using Spring profiles, with application.properties, application-dev.properties, and application-prod.properties. The README indicates MySQL is the backing datastore and is commonly run in Docker, so the main external infrastructure boundary is the database container rather than an embedded store.
11. Swagger/OpenAPI is included for API documentation, which means the controllers are intended to be discoverable and testable through generated docs, typically at /swagger-ui/index.html. The README also mentions Actuator support, so operational endpoints are part of the runtime surface.
12. The repository is currently a backend-only monolith with no security layer implemented yet. The README’s next steps call out registration/login and JWT-based Spring Security, so authentication/authorization is intentionally absent from the current architecture.
13. For an architecture diagram, the important flow is: client request → controller → validated DTO → service → JPA repository → MySQL → entity/DTO mapping → controller response. The cross-cutting concern is the global exception handler, which intercepts failures from any layer and returns consistent error payloads.
Main entry points: GlobalExceptionHandler.java Exception Handler · ExpenseService.java Expense Service · ExpenseController.java Expense API · UserController.java User API
Components 23
Runtime
Spring Boot application entrypoint and runtime surface
- ExpenseTrackerApp · Main application entrypoint that boots the Spring container
expense-tracker/src/main/java/com/example/expense_tracker/ExpenseTrackerApplication.java
API Layer
HTTP controllers and request/response contracts
- User API · HTTP boundary for user operations
expense-tracker/src/main/java/com/example/expense_tracker/controller/UserController.java - Category API · HTTP boundary for category operations
expense-tracker/src/main/java/com/example/expense_tracker/controller/CategoryController.java - Expense API · HTTP boundary for expense operations
expense-tracker/src/main/java/com/example/expense_tracker/controller/ExpenseController.java - User Service · User business rules and validation-dependent logic
expense-tracker/src/main/java/com/example/expense_tracker/service/UserService.java - Category Service · Category business rules and validation-dependent logic
expense-tracker/src/main/java/com/example/expense_tracker/service/CategoryService.java - Expense Service · Expense workflow, filtering, and cross-entity checks
expense-tracker/src/main/java/com/example/expense_tracker/service/ExpenseService.java - CreateUserRequest · Validated input for creating users
expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateUserRequest.java - CategoryRequest · Validated input for category mutations
expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CategoryRequest.java - CreateExpenseRequest · Validated input for creating expenses
expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateExpenseRequest.java - ExpenseRequest · Validated input for expense queries and updates
expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/ExpenseRequest.java - UserResponse · API representation of users
expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/UserResponse.java - CategoryResponse · API representation of categories
expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/CategoryResponse.java - ExpenseResponse · API representation of expenses
expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ExpenseResponse.java
Domain
Core expense tracking entities and persistence boundary
- User · User domain model and persistence record
expense-tracker/src/main/java/com/example/expense_tracker/entity/User.java - Category · Expense category domain model and persistence record
expense-tracker/src/main/java/com/example/expense_tracker/entity/Category.java - Expense · Central expense fact linking users and categories
expense-tracker/src/main/java/com/example/expense_tracker/entity/Expense.java - User Repo · Data access for users
expense-tracker/src/main/java/com/example/expense_tracker/repository/UserRepository.java - Category Repo · Data access for categories
expense-tracker/src/main/java/com/example/expense_tracker/repository/CategoryRepository.java - Expense Repo · Data access for expenses and queries
expense-tracker/src/main/java/com/example/expense_tracker/repository/ExpenseRepository.java
Cross-cutting
Exception handling and application configuration
- ErrorResponse · Standardized API error payload
expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ErrorResponse.java - Exception Handler · Maps domain and framework exceptions to API errors
expense-tracker/src/main/java/com/example/expense_tracker/exception/GlobalExceptionHandler.java - Not Found Errors · User, category, expense, and email conflict exceptions
Connections 31
- ExpenseTrackerApp → User API: wires · Application context exposes user endpoints
- ExpenseTrackerApp → Category API: wires · Application context exposes category endpoints
- ExpenseTrackerApp → Expense API: wires · Application context exposes expense endpoints
- User API → CreateUserRequest: binds · Validates incoming user input
- Category API → CategoryRequest: binds · Validates incoming category input
- Expense API → CreateExpenseRequest: binds · Validates incoming expense creation input
- Expense API → ExpenseRequest: binds · Validates incoming expense query/update input
- User API → User Service: delegates · Routes user actions to business logic
- Category API → Category Service: delegates · Routes category actions to business logic
- Expense API → Expense Service: delegates · Routes expense actions to business logic
- User Service → User Repo: uses · Persists and loads users
- Category Service → Category Repo: uses · Persists and loads categories
- Expense Service → Expense Repo: uses · Persists and queries expenses
- Expense Service → User Repo: checks · Verifies referenced users exist
- Expense Service → Category Repo: checks · Verifies referenced categories exist
- Expense Repo → Expense: maps · Repository operates on expense records
- User Repo → User: maps · Repository operates on user records
- Category Repo → Category: maps · Repository operates on category records
- Expense → User: relates to · Each expense belongs to a user
- Expense → Category: relates to · Each expense belongs to a category
- User Service → UserResponse: returns · Shapes user API output
- Category Service → CategoryResponse: returns · Shapes category API output
- Expense Service → ExpenseResponse: returns · Shapes expense API output
- Exception Handler → ErrorResponse: emits · Produces consistent error payloads
- Not Found Errors → Exception Handler: handled by · Translated into structured API errors
- User API → Exception Handler: raises · Controller failures are intercepted centrally
- Category API → Exception Handler: raises · Controller failures are intercepted centrally
- Expense API → Exception Handler: raises · Controller failures are intercepted centrally
- User Service → Exception Handler: raises · Service failures are intercepted centrally
- Category Service → Exception Handler: raises · Service failures are intercepted centrally
- Expense Service → Exception Handler: raises · Service failures are intercepted centrally