💰 Capital Gains Calculator

Technical challenge for a Software Engineer position in Nubank.

This project implements a command-line application that calculates the capital gains tax for stock trading operations, based on defined business rules like weighted average pricing, tax exemption thresholds, and loss compensation.

---

⚠️ Requirements

• Java 24 or higher is required to run this project.
  If you don't have Java 24 installed, download it from:
  ➡️ https://jdk.java.net/24/

Check your Java version:

java -version

Expected output:

openjdk version "24"

✅ The application runs on Windows, macOS, and Linux, as long as Java 24 is installed.

---

🚀 How it works

The application reads a list of operations from stdin, one per line in JSON format. Each line is processed to calculate the tax for each operation, and the result is returned to stdout.

✅ Supported operations:

• "buy": increases the number of shares and updates the average price.
• "sell": calculates gain/loss, applies exemption (≤ R$20,000), and applies 20% tax if applicable.

---

🛠 How to run

1. Build the project:

./gradlew clean build

2. Run the application:

java -jar build/libs/capital-gains-0.0.1-SNAPSHOT.jar

The program will start and wait for input in the terminal (stdin).

---

🔥 How to provide input

You can type or paste a JSON line directly into the terminal and press Enter.

✅ Example input:

[{"operation":"buy", "unit-cost":10.00, "quantity":10000}, {"operation":"sell", "unit-cost":20.00, "quantity":5000}]

✅ Example output:

[{"tax":0.00},{"tax":10000.00}]

💡 To exit the program:

• On macOS/Linux: Ctrl + D
• On Windows: Enter

---

🔥 Alternative: Run with input from a file

1. Create an input.txt file with:

[{"operation":"buy", "unit-cost":10.00, "quantity":10000}, {"operation":"sell", "unit-cost":20.00, "quantity":5000}]

2. Run (do not use Windows PowerShell):

java -jar build/libs/capital-gains-0.0.1-SNAPSHOT.jar < input.txt

Output:

[{"tax":0.00},{"tax":10000.00}]

---

✅ How to test

Run unit and integration tests with:

./gradlew test

All test cases from the code challenge document are included in these tests.

---

📦 Project structure

src/
├── main/
│   ├── java/com/nubank/capitalgains/
│   │   ├── CapitalGainsApplication.java
│   │   ├── cli/CommandLineInterface.java
│   │   ├── calculator/CapitalGainCalculator.java
│   │   ├── model/
│   │   │   ├── OperationInput.java
│   │   │   └── TaxOutput.java
│   │   └── service/OperationProcessor.java
│
└── test/
    └── java/com/nubank/capitalgains/
        ├── calculator/
        │   ├── CapitalGainCalculatorTest.java
        │   └── CapitalGainCalculatorTestCases.java
        └── integration/
            └── CommandLineInterfaceIntegrationTest.java

---

⚙️ Tech stack

• Java 24
• Spring Boot 3.2+
• Gradle Kotlin DSL
• Jackson for JSON parsing
• JUnit 5 for testing

---

🧠 Design Decisions

• Immutability
  Models are defined as Java record types to ensure immutability, improving code clarity, thread-safety, and preventing accidental state mutations.

• Precision in Financial Calculations
  All monetary computations use BigDecimal with explicit scale and rounding mode to avoid floating-point inaccuracies, which is critical in financial applications.

• Separation of Concerns & Scalability
  Business logic is fully encapsulated within the CapitalGainCalculator class.
  Input/output handling is decoupled from the core logic.
  This design allows the calculator to be easily reused in different contexts, such as APIs, batch processes, or UIs, without modification.

• Testability & Robustness
  The test suite mirrors exactly the test cases described in the original challenge document (spec-ptbr.pdf), from case #1 to case #9, with both unit tests and a full integration test simulating the real CLI execution.
  Implemented using JUnit 5's @ParameterizedTest with Arguments.of to improve test readability, eliminate duplication, and enable systematic validation of all business scenarios.

  Test coverage includes:

  • Price average calculation (weighted average)
  • Tax exemption rules
  • Loss accumulation and compensation
  • Boundary conditions and edge cases
  • Full integration test covering the execution from the command-line interface (CLI) to the core calculation logic

• Code Quality & Readability
  The implementation adheres to SOLID principles, Clean Code, and Clean Architecture practices.

  Responsibilities are well-defined:

  • Models → pure data
  • Calculator → business logic
  • Processor/Service → orchestration
  • CLI → user input/output management

• Simplicity and Maintainability
  The project intentionally avoids unnecessary frameworks or dependencies, keeping the code lean, maintainable, and easy to understand during code review processes or handoffs.

---