|
1 | | -# Financial Transfers API |
| 1 | +# Portfolio |
2 | 2 |
|
3 | | -This project consists of a RESTful API for customer management and financial transfers. |
| 3 | +> Check out my [website](https://pedroreis.dev) |
4 | 4 |
|
5 | | -## Technologies and Requirements |
| 5 | +Portfolio Java web application that displays project statistics, with a traditional MVC architecture using Spring Boot controllers, models, and JTE templates for the view layer. |
6 | 6 |
|
7 | | -* **Java 25** |
8 | | -* **Spring Boot 4** |
9 | | -* **H2** |
10 | | -* **Maven** |
| 7 | +## Tech Stack |
11 | 8 |
|
12 | | -## How to Run the Application |
| 9 | +- Java 25 |
13 | 10 |
|
14 | | -1. **Prerequisites**: Make sure you have **JDK 21** and **Maven** installed. |
15 | | -2. **Clone the repository**: |
| 11 | +- Spring Boot 3.5.7 |
16 | 12 |
|
17 | | -```bash |
18 | | -git clone https://github.com/barcellos-pedro/api-transferencia.git |
19 | | -cd api-transferencia |
20 | | -``` |
| 13 | +- Spring Web (REST controllers) |
21 | 14 |
|
22 | | -1. **Compile and run**: |
| 15 | +- Spring JDBC (database access) |
23 | 16 |
|
24 | | -```bash |
25 | | -mvn spring-boot:run |
26 | | -``` |
| 17 | +- SQLite (lightweight file-based database) |
27 | 18 |
|
28 | | -1. **Access the API**: The application will be available at `http://localhost:8080`. |
29 | | -2. **Interactive Documentation (Swagger)**: Access `http://localhost:8080/swagger-ui/index.html` to test the endpoints |
30 | | - in the browser |
| 19 | +- `database.db` is the local database file, and it is not versioned. |
| 20 | +Templating: |
31 | 21 |
|
32 | | -## Main Endpoints |
| 22 | +- JTE (Java Template Engine) 3.2.1 for server-side HTML rendering |
| 23 | +Build & Deployment: |
33 | 24 |
|
34 | | -The API follows RESTful patterns and URL versioning (`/v1/...`): |
| 25 | +- Maven (build tool and dependency management) |
35 | 26 |
|
36 | | -**Customers**: |
| 27 | +- GitHub Actions for CI/CD |
| 28 | +Additional Libraries: |
37 | 29 |
|
38 | | -* `GET /v1/customers`: General customer listing. |
39 | | -* `POST /v1/customers`: Register new customer. |
40 | | -* `GET /v1/customers/{account}`: Search Customer by account number. |
41 | | -* `GET /v1/customers/{account}/transfers`: History ordered by descending date, including failures. |
42 | | -* `POST /v1/customers/{account}/transfers`: Perform transfer between accounts (Limit of R$ 10,000.00). |
| 30 | +- Jackson (JSON processing with JSR310 datetime support) |
43 | 31 |
|
44 | | -## Additional Endpoints |
45 | | - |
46 | | -* `GET /api-docs` - OpenAPI specification in JSON. |
47 | | -* `GET /actuator/health`: Application health check. |
48 | | -* `GET /swagger-ui/index.html`: Visual interface to test API endpoints. |
49 | | - |
50 | | -## Monitoring and Documentation |
51 | | - |
52 | | -The API uses Spring Boot Actuator to provide metrics and health status, essential for production environments and |
53 | | -observability. |
54 | | - |
55 | | -**Diagnostic Endpoints (Actuator)** |
56 | | - |
57 | | -| Endpoint | Description | Purpose | |
58 | | -|-----------------------|--------------------|---------------------------------------------------------| |
59 | | -| GET /actuator/health | Application Health | Checks if App, DB and Disk are operational. | |
60 | | -| GET /actuator/metrics | Metrics | Lists available metrics (JVM, CPU, HTTP Requests). | |
61 | | -| GET /actuator/info | Information | Custom data about project version and build. | |
62 | | - |
63 | | -## Engineering & Architecture Decisions |
64 | | - |
65 | | -### 1. History Resilience |
66 | | - |
67 | | -As requested, unsuccessful transfers are also stored. To ensure that the failure record is |
68 | | -persisted even when the financial transaction suffers rollback, I used **`REQUIRES_NEW`** propagation in the audit |
69 | | -service. This guarantees the integrity of the history for banking compliance. |
70 | | - |
71 | | -### 2. Concurrency Control |
72 | | - |
73 | | -To meet the concurrency control requirement in the transfer operation, the following was implemented: |
74 | | - |
75 | | -* **Pessimistic Locking** (or **Optimistic Locking** with `@Version`): To avoid the "Lost Update" problem when |
76 | | - two processes try to debit from the same account simultaneously. |
77 | | - |
78 | | -### 3. Business Rules Validation |
79 | | - |
80 | | -The rules of sufficient balance and maximum limit of R$ 10,000.00 per operation were centralized in the service layer, |
81 | | -ensuring that the database state remains consistent. |
82 | | - |
83 | | -## Tests |
84 | | - |
85 | | -Test coverage was prioritized to ensure the reliability of transfers: |
86 | | - |
87 | | -* **Unit Tests**: Validation of business logic and balance calculations. |
88 | | -* **Integration Tests**: Complete transfer flow simulating concurrency and database rollback. |
89 | | - |
90 | | -Run the tests with: |
91 | | - |
92 | | -```bash |
93 | | -mvn test |
94 | | -``` |
95 | | - |
96 | | -## Project Base |
97 | | - |
98 | | -The project was structured using [Spring Initializr](https://start.spring.io). |
99 | | - |
100 | | -**Technology Stack and Dependencies** |
101 | | - |
102 | | -Below, the main components selected to meet the API requirements: |
103 | | - |
104 | | -<img width="1710" height="654" alt="image" src="https://github.com/user-attachments/assets/35a7e8da-9396-4ad3-944b-87a0fa95573a" /> |
| 32 | +- Spring Boot DevTools (development tools) |
0 commit comments