# aditya9u/expense-tracker-backend architecture

> Architecture diagram of the GitHub repository aditya9u/expense-tracker-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditya9u/expense-tracker-backend
- Repository: https://github.com/aditya9u/expense-tracker-backend

## Overview

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: [`expense-tracker/src/main/java/com/example/expense_tracker/exception/GlobalExceptionHandler.java`](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/exception/GlobalExceptionHandler.java) (Exception Handler), [`expense-tracker/src/main/java/com/example/expense_tracker/service/ExpenseService.java`](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/ExpenseService.java) (Expense Service), [`expense-tracker/src/main/java/com/example/expense_tracker/controller/ExpenseController.java`](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/ExpenseController.java) (Expense API), [`expense-tracker/src/main/java/com/example/expense_tracker/controller/UserController.java`](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/UserController.java) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app(("ExpenseTrackerApp<br/>spring boot app"))
end

subgraph group_api["API Layer"]
  node_user_controller["User API<br/>controller"]
  node_category_controller["Category API<br/>controller"]
  node_expense_controller["Expense API<br/>controller"]
  node_user_service["User Service<br/>[UserService.java]"]
  node_category_service["Category Service"]
  node_expense_service["Expense Service"]
  node_create_user_request["CreateUserRequest<br/>request dto"]
  node_category_request["CategoryRequest<br/>request dto"]
  node_create_expense_request["CreateExpenseRequest<br/>request dto"]
  node_expense_request["ExpenseRequest<br/>request dto"]
  node_user_response["UserResponse<br/>response dto<br/>[UserResponse.java]"]
  node_category_response["CategoryResponse<br/>response dto"]
  node_expense_response["ExpenseResponse<br/>response dto"]
end

subgraph group_domain["Domain"]
  node_user_entity[("User<br/>jpa entity<br/>[User.java]")]
  node_category_entity[("Category<br/>jpa entity<br/>[Category.java]")]
  node_expense_entity[("Expense<br/>jpa entity<br/>[Expense.java]")]
  node_user_repo["User Repo<br/>jpa repository"]
  node_category_repo["Category Repo<br/>jpa repository"]
  node_expense_repo["Expense Repo<br/>jpa repository"]
end

subgraph group_infra["Cross-cutting"]
  node_error_response["ErrorResponse<br/>response dto<br/>[ErrorResponse.java]"]
  node_global_handler["Exception Handler<br/>controller advice"]
  node_exceptions{{"Not Found Errors<br/>domain exceptions"}}
end

node_app -->|"wires"| node_user_controller
node_app -->|"wires"| node_category_controller
node_app -->|"wires"| node_expense_controller
node_user_controller -->|"binds"| node_create_user_request
node_category_controller -->|"binds"| node_category_request
node_expense_controller -->|"binds"| node_create_expense_request
node_expense_controller -->|"binds"| node_expense_request
node_user_controller -->|"delegates"| node_user_service
node_category_controller -->|"delegates"| node_category_service
node_expense_controller -->|"delegates"| node_expense_service
node_user_service -->|"uses"| node_user_repo
node_category_service -->|"uses"| node_category_repo
node_expense_service -->|"uses"| node_expense_repo
node_expense_service -->|"checks"| node_user_repo
node_expense_service -->|"checks"| node_category_repo
node_expense_repo -->|"maps"| node_expense_entity
node_user_repo -->|"maps"| node_user_entity
node_category_repo -->|"maps"| node_category_entity
node_expense_entity -->|"relates to"| node_user_entity
node_expense_entity -->|"relates to"| node_category_entity
node_user_service -->|"returns"| node_user_response
node_category_service -->|"returns"| node_category_response
node_expense_service -->|"returns"| node_expense_response
node_global_handler -->|"emits"| node_error_response
node_exceptions -->|"handled by"| node_global_handler
node_user_controller -.->|"raises"| node_global_handler
node_category_controller -.->|"raises"| node_global_handler
node_expense_controller -.->|"raises"| node_global_handler
node_user_service -.->|"raises"| node_global_handler
node_category_service -.->|"raises"| node_global_handler
node_expense_service -.->|"raises"| node_global_handler

click node_app "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/ExpenseTrackerApplication.java"
click node_user_controller "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/UserController.java"
click node_category_controller "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/CategoryController.java"
click node_expense_controller "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/ExpenseController.java"
click node_user_service "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/UserService.java"
click node_category_service "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/CategoryService.java"
click node_expense_service "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/ExpenseService.java"
click node_create_user_request "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateUserRequest.java"
click node_category_request "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CategoryRequest.java"
click node_create_expense_request "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateExpenseRequest.java"
click node_expense_request "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/ExpenseRequest.java"
click node_user_entity "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/entity/User.java"
click node_category_entity "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/entity/Category.java"
click node_expense_entity "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/entity/Expense.java"
click node_user_repo "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/repository/UserRepository.java"
click node_category_repo "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/repository/CategoryRepository.java"
click node_expense_repo "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/repository/ExpenseRepository.java"
click node_user_response "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/UserResponse.java"
click node_category_response "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/CategoryResponse.java"
click node_expense_response "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ExpenseResponse.java"
click node_error_response "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ErrorResponse.java"
click node_global_handler "https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/exception/GlobalExceptionHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_user_controller,node_category_controller,node_expense_controller,node_user_service,node_category_service,node_expense_service,node_create_user_request,node_category_request,node_create_expense_request,node_expense_request,node_user_response,node_category_response,node_expense_response toneAmber
class node_user_entity,node_category_entity,node_expense_entity,node_user_repo,node_category_repo,node_expense_repo toneMint
class node_error_response,node_global_handler,node_exceptions toneRose
```

## Components

### Runtime

Spring Boot application entrypoint and runtime surface

- [ExpenseTrackerApp](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/ExpenseTrackerApplication.java): spring boot app · 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](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/UserController.java): controller · HTTP boundary for user operations · `expense-tracker/src/main/java/com/example/expense_tracker/controller/UserController.java`
- [Category API](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/CategoryController.java): controller · HTTP boundary for category operations · `expense-tracker/src/main/java/com/example/expense_tracker/controller/CategoryController.java`
- [Expense API](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/controller/ExpenseController.java): controller · HTTP boundary for expense operations · `expense-tracker/src/main/java/com/example/expense_tracker/controller/ExpenseController.java`
- [User Service](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/UserService.java): service · User business rules and validation-dependent logic · `expense-tracker/src/main/java/com/example/expense_tracker/service/UserService.java`
- [Category Service](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/CategoryService.java): service · Category business rules and validation-dependent logic · `expense-tracker/src/main/java/com/example/expense_tracker/service/CategoryService.java`
- [Expense Service](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/service/ExpenseService.java): service · Expense workflow, filtering, and cross-entity checks · `expense-tracker/src/main/java/com/example/expense_tracker/service/ExpenseService.java`
- [CreateUserRequest](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateUserRequest.java): request dto · Validated input for creating users · `expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateUserRequest.java`
- [CategoryRequest](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CategoryRequest.java): request dto · Validated input for category mutations · `expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CategoryRequest.java`
- [CreateExpenseRequest](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateExpenseRequest.java): request dto · Validated input for creating expenses · `expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/CreateExpenseRequest.java`
- [ExpenseRequest](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/ExpenseRequest.java): request dto · Validated input for expense queries and updates · `expense-tracker/src/main/java/com/example/expense_tracker/dto/requests/ExpenseRequest.java`
- [UserResponse](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/UserResponse.java): response dto · API representation of users · `expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/UserResponse.java`
- [CategoryResponse](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/CategoryResponse.java): response dto · API representation of categories · `expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/CategoryResponse.java`
- [ExpenseResponse](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ExpenseResponse.java): response dto · 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](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/entity/User.java): jpa entity · User domain model and persistence record · `expense-tracker/src/main/java/com/example/expense_tracker/entity/User.java`
- [Category](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/entity/Category.java): jpa entity · Expense category domain model and persistence record · `expense-tracker/src/main/java/com/example/expense_tracker/entity/Category.java`
- [Expense](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/entity/Expense.java): jpa entity · Central expense fact linking users and categories · `expense-tracker/src/main/java/com/example/expense_tracker/entity/Expense.java`
- [User Repo](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/repository/UserRepository.java): jpa repository · Data access for users · `expense-tracker/src/main/java/com/example/expense_tracker/repository/UserRepository.java`
- [Category Repo](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/repository/CategoryRepository.java): jpa repository · Data access for categories · `expense-tracker/src/main/java/com/example/expense_tracker/repository/CategoryRepository.java`
- [Expense Repo](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/repository/ExpenseRepository.java): jpa repository · 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](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ErrorResponse.java): response dto · Standardized API error payload · `expense-tracker/src/main/java/com/example/expense_tracker/dto/responses/ErrorResponse.java`
- [Exception Handler](https://github.com/aditya9u/expense-tracker-backend/blob/main/expense-tracker/src/main/java/com/example/expense_tracker/exception/GlobalExceptionHandler.java): controller advice · Maps domain and framework exceptions to API errors · `expense-tracker/src/main/java/com/example/expense_tracker/exception/GlobalExceptionHandler.java`
- **Not Found Errors**: domain exceptions · User, category, expense, and email conflict exceptions

## Connections

- 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
