CFinance

Financial Control System Built with Java

Description

CFinance is a backend application designed to help manage financial data such as expenses and income, following modern backend architecture and best practices.

Prerequisites

• Docker and Docker Compose
• Java 21 (for local development)
• Maven

Technologies

This application uses the following technologies:

• Java 21
• Spring Boot framework
  • Spring Security
  • JPA / Hibernate
  • Flyway (Database migrations)
  • Swagger / OpenAPI (API Documentation)
• JUnit & Mockito (Testing)
• PostgreSQL
• Docker & Docker Compose
• Maven

Structure

This API is built following Clean Architecture principles, which isolates the business model (usecases) to the external framework / dependencies.

Main endpoints

Below are the main endpoints, but you may check at api documentation section

Method	Endpoint
POST	/api/auth/register
POST	/api/auth/login
GET	/api/payment-method
POST	/api/transaction

Register

Perform a new user register

curl -X 'POST' \
  'http://localhost:1234/api/auth/register' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "kbill",
  "password": "V6w426M42s96"
}'

Login

Login endpoint. On success, it returns a JWT token

curl -X 'POST' \
  'http://localhost:1234/api/auth/login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "kbill",
  "password": "V6w426M42s96"
}'

Payment methods

List all payment methods available

curl -X 'GET' \
  'http://localhost:1234/api/payment-method' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create an expense transaction

Create an expense transaction paid in cash. Attention to 'installment' flag

curl -X 'POST' \
  'http://localhost:1234/api/transaction' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN> ' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Keyboard",
  "valueTransaction": 60.00,
  "type": "EXPENSE",
  "category": 1,
  "transactionDate": "2025-12-20T09:00:00",
  "paymentMethodId": 3,
  "installmentNumber": 0,
  "totalInstallment": 0,
  "creditCardId": null,
  "observations": "Mechanical Keyboard",
  "installment": false
}'

You can also create an income transaction:

curl -X 'POST' \
  'http://localhost:1234/api/transaction' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Salary",
  "valueTransaction": 7000.00,
  "type": "INCOME",
  "category": 1,
  "transactionDate": "2025-12-20T09:00:00",
  "paymentMethodId": 3,
  "installmentNumber": 0,
  "totalInstallment": 0,
  "creditCardId": null,
  "observations": "Monthly salary",
  "installment": false
}'

Installation

1. Clone the repository:

git clone https://github.com/igorsoares/CFinance.git

2. Enter the project folder

cd CFinance

3. Run docker-compose command

docker-compose up -d

The application will start along with its required dependencies (e.g., PostgreSQL).

Api Documentation

Once the application is running, you can access the Swagger UI at:

http://localhost:1234/swagger-ui/index.html

Tests

To run the tests:

If you have the maven installed:

mvn test

If don't:

chmod +x ./mvnw && ./mvnw test

Contributing

To maintain the code quality please follow these guidelines:

Clean Architecture

This project follows Clean Architecture principles. Please ensure your contributions respect the separation of concerns:

• Entities/Domain: Business logic and domain models
• Use Cases: Application-specific business rules
• Interface Adapters: Controllers, presenters, and gateways
• Frameworks & Drivers: External frameworks, databases, and UI

Unit Testing

All new feature and bug fixes must include unit tests. We use:

• JUnit 5 for test structure
• Mockito for mocking dependencies

API Documentation

All endpoints must be documented using Swagger/OpenAPI annotations. Use @Operation to describe your endpoints clearly, example:

@Operation(
    summary="Get user data",
    description="Retrieve user data such as username, categories and most spend category type"
)
@GetMapping
public ResponseEntity<UserDataResponse> getUserData(){
    // Your logic
    return ResponseEntity.ok().build();
};