DEV Community: Marcin Parśniak

Building Shared Accounts in Finovara

Marcin Parśniak — Thu, 23 Jul 2026 16:04:42 +0000

When I added shared accounts to Finovara (two users sharing one wallet, expenses, limits, and piggy banks), I knew it would touch almost every service I already had — auth-backend, finance-backend, notification-backend. This post walks through three parts of that feature that I think turned out well: the invitation flow, settings that live per-pair-of-users, and safely tearing down shared financial data when someone leaves.

The Core Idea: `ownerId` + `memberId`, Not a Shared User Table

A shared account in Finovara isn't a separate "super user." It's a pairing of two existing accounts — an owner and a member — and every shared entity (wallet, expenses, limits, piggy banks, settings) just carries both IDs:

@Column(nullable = false)
private Long ownerId;

@Column(nullable = false)
private Long memberId;

This keeps things simple: no new authentication concept, no "shared user" identity to manage. Just two foreign keys and a unique constraint on (owner_id, member_id) to guarantee one shared entity per pair.

Part 1: The Invitation Flow

Before two users can share anything, one has to invite the other. Here's the validation layer that guards this:

public void validateSendInvitation(Long inviterUserId, Long inviteeUserId) {
    if (inviterUserId.equals(inviteeUserId)) {
        log.warn("Rejected invitation: userId={} tried to invite themselves", inviterUserId);
        throw new InvalidInputException("You cannot invite yourself");
    }

    if (sharedAccountMemberRepository.existsByUserId(inviterUserId) || sharedAccountMemberRepository.existsByUserId(inviteeUserId)) {
        log.warn("Rejected invitation: inviterUserId={} or inviteeUserId={} already has a shared account", inviterUserId, inviteeUserId);
        throw new EntityAlreadyExistsException("One of the users already belongs to a shared account");
    }

    sharedAccountInvitationRepository.findInvitationBetweenUsers(inviterUserId, inviteeUserId)
            .ifPresent(invitation -> {
                log.warn("Rejected invitation: invitation already exists between inviterUserId={} and inviteeUserId={}", inviterUserId, inviteeUserId);
                throw new EntityAlreadyExistsException("Invitation already exists between these users!");
            });
}

Three checks, three clear failure reasons: no self-invites, no double-membership (a user can only belong to one shared account), and no duplicate pending invitations. Each rejection is logged with the relevant IDs, which turned out to be invaluable later when debugging race conditions between two people accepting/cancelling invitations at nearly the same time.

Sending the Invitation — and Firing Off Three Different Events

Here's where it gets interesting. A single sendInvitation call needs to do three unrelated things: persist the invitation, record it in the activity log, and notify the invitee. Instead of coupling those responsibilities together, I lean on the outbox pattern:

@Transactional
public void sendInvitation(Long inviterUserId, Long inviteeUserId) {
    invitationValidator.validateSendInvitation(inviterUserId, inviteeUserId);

    // ...load inviter/invitee basic info...

    SharedAccountInvitation invitation = SharedAccountInvitation.builder()
            .inviterUserId(inviterUserId)
            .inviteeUserId(inviteeUserId)
            .createdAt(LocalDateTime.now())
            .build();

    sharedAccountInvitationRepository.save(invitation);

    outboxService.save("User", inviterUserId.toString(), "activity.shared-account",
            new SharedAccountActivityEvent(inviterUserId, SharedAccountActivityType.SENT_INVITATION, null, invitee.username(), invitee.email(), LocalDateTime.now()));

    outboxService.save("User", inviterUserId.toString(), "notification.shared-account.invitation-sent",
            new UserSentSharedAccountInvitationEvent(inviteeUserId, inviter.username()));

    log.info("Created invitation id={}, inviterUserId={}, inviteeUserId={}", invitation.getId(), inviterUserId, inviteeUserId);
}

The key detail: sharedAccountInvitationRepository.save(...) and both outboxService.save(...) calls happen inside the same @Transactional boundary. Since the outbox table lives in the same database as the invitation itself, all three inserts commit or roll back together. There's no scenario where an invitation is created but the notification event silently disappears because Kafka happened to be down for a second — the event just sits in the outbox table until a relay process picks it up and publishes it.

This is the same reasoning I apply to every cross-service side-effect in Finovara now: if it needs to be atomic with a database write, it goes through the outbox — never a direct kafkaTemplate.send() in the middle of a transaction.

Accepting an Invitation Creates the Shared Account — and Cascades Four More Events

@Transactional
public void acceptInvite(Long inviteeUserId, Long invitationId) {
    SharedAccountInvitation invitation = loadAndValidateInvitation(inviteeUserId, invitationId);
    Long inviterUserId = invitation.getInviterUserId();

    invitationValidator.validateAcceptInvite(inviterUserId, inviteeUserId, invitationId);

    // ...load user data...

    sharedAccountInvitationRepository.deleteInvitationById(invitationId);

    SharedAccount sharedAccount = sharedAccountRepository.save(
            SharedAccount.builder().createdAt(LocalDateTime.now()).build());

    createMember(sharedAccount, inviterUserId, SharedRole.OWNER);
    createMember(sharedAccount, inviteeUserId, SharedRole.MEMBER);

    outboxService.save("User", inviterUserId.toString(),
            "finance.shared-account.invitation-accepted",
            new UsersCreatedSharedAccountEvent(inviterUserId, inviteeUserId));

    outboxService.save("User", inviteeUserId.toString(),
            "finance.shared-account.create-default-settings",
            new SharedAccountCreateDefaultSettingsEvent(inviterUserId, inviteeUserId));

    outboxService.save("User", inviteeUserId.toString(), "activity.shared-account",
            new SharedAccountActivityEvent(inviteeUserId, SharedAccountActivityType.ACCEPTED_INVITATION, null,
                    inviter.username(), inviter.email(), LocalDateTime.now()));

    outboxService.save("User", inviterUserId.toString(),
            "notification.shared-account.invitation-accepted",
            new UserAcceptSharedAccountInvitationEvent(inviterUserId, invitee.username()));
}

One accepted invitation, four downstream events, and auth-backend doesn't need to know or care what any of them trigger. finance-backend listens for finance.shared-account.invitation-accepted and creates the shared wallet; it listens for finance.shared-account.create-default-settings and provisions a default SharedAccountSettings row; activity-log-backend and notification-backend handle their own topics independently. Each service only knows its own responsibility — that's the whole point of the split.

Part 2: Settings That Belong to a Pair, Not a User

This is the part I initially got wrong in my head before writing any code: shared account settings aren't owned by a single user — they're owned by the relationship between two users. That's why SharedAccountSettings (and every shared entity, really) is looked up by:

@Query("SELECT sa FROM SharedAccountSettings sa WHERE sa.ownerId = :userId OR sa.memberId = :userId")
SharedAccountSettings findByUserId(Long userId);

Either party can query "their" shared settings, and they both get back the same row. A toggle like "notify me on large expenses" isn't "my setting", it's "our setting." This single design decision cascades through every feature built on top of shared accounts: spend control, expense analysis, large-expense notifications, piggy bank goal notifications — they all key off the same (ownerId, memberId) pair.

Part 3: Deleting a Shared Account Without Losing Money

This is the part I'm proudest of. When one person leaves a shared account (or deletes their user account entirely), Finovara has to:

Refund whatever money each person actually contributed, based on their net revenue minus expenses within the shared account.
Delete every trace of shared financial data — expenses, revenues, wallet, piggy banks, limits, notes, settings.
Evict stale cache entries so neither party sees a phantom balance.
Do all of this idempotently, because Kafka will redeliver messages.

Idempotency First

@Transactional(propagation = Propagation.REQUIRES_NEW)
public boolean deleteData(SharedAccountDeletedEvent event) {
    Long ownerId = Objects.requireNonNull(event.ownerId(), "event.ownerId must not be null");
    Long memberId = Objects.requireNonNull(event.memberId(), "event.memberId must not be null");

    if (!sharedWalletRepository.existsByOwnerIdAndMemberId(ownerId, memberId)) {
        log.info("Shared account financial data already deleted for accountId={}, ownerId={}, memberId={} " +
                "(duplicate Kafka delivery) — skipping.", event.accountId(), ownerId, memberId);
        return false;
    }

    refundContributedRevenue(event);
    deleteSharedFinancialData(ownerId, memberId);
    return true;
}

Before doing anything destructive, I check whether the shared wallet still exists. If it doesn't, this event has already been processed once — return early, log it clearly as a duplicate delivery, and don't touch anything twice. This one if statement is what makes the whole consumer safe to retry.

Refunding Fairly When Both Sides Contributed Differently

The interesting logic is in figuring out who gets what back. Each person's net contribution is revenue - expense within the shared account:

private record NetContribution(BigDecimal revenue, BigDecimal expense) {
    BigDecimal net() {
        return revenue.subtract(expense);
    }
    boolean isNegative() {
        return net().compareTo(BigDecimal.ZERO) < 0;
    }
}

But what happens if one person's net contribution is negative — they spent more of the shared pool than they put in? You can't refund them money they never contributed. So the logic redistributes:

if (ownerContribution.isNegative()) {
    ownerRefund = BigDecimal.ZERO;
    memberRefund = ownerContribution.net().add(memberContribution.net()).max(BigDecimal.ZERO);
} else if (memberContribution.isNegative()) {
    memberRefund = BigDecimal.ZERO;
    ownerRefund = ownerContribution.net().add(memberContribution.net()).max(BigDecimal.ZERO);
} else {
    ownerRefund = ownerContribution.net();
    memberRefund = memberContribution.net();
}

If one side is in the negative, they get nothing back, and the other side's refund is the combined net — but clamped at zero, so nobody ever gets refunded a negative amount by accident. Each refund path also gracefully skips if the target user's personal wallet no longer exists (a legitimate edge case when both users happen to delete their accounts around the same time):

try {
    walletService.addBalanceToWallet(instruction.userId(), instruction.amount());
} catch (RequestedEntityNotFoundException ex) {
    log.warn("Refund skipped for userId={} — personal wallet no longer exists " +
            "(likely concurrent full account deletion). amount={}", instruction.userId(), instruction.amount());
    return;
}

Cleanup and Cache Eviction Are Separate Concerns

The deletion handler itself stays intentionally thin:

public void handle(SharedAccountDeletedEvent event) {
    boolean wasDeleted = financeDataService.deleteData(event);
    if (wasDeleted) {
        cacheEvictionService.evictAfterSharedAccountDeletion(event.ownerId(), event.memberId());
    }
}

Cache eviction only runs if data was actually deleted (skipping it on duplicate deliveries, same as everything else), and it's defensive about failure — a cache eviction that throws shouldn't take down the whole deletion process, since the cache entry will simply expire on its own TTL:

private void evictIfPresent(String cacheName, Object key) {
    try {
        var cache = cacheManager.getCache(cacheName);
        if (cache != null) {
            cache.evict(key);
        }
    } catch (Exception ex) {
        log.warn("Cache eviction failed for cache={}, key={} — entry may be stale until TTL expiry.",
                cacheName, key, ex);
    }
}

Wiring It All Into the Expense Flow

All of this settings/notification infrastructure ultimately plugs into the same place: adding a shared expense.

@Transactional
public SharedExpenseResponse addExpense(SharedExpenseRequest sharedExpenseRequest, Long userId) {
    // ...validation...

    spendControlService.handleSpendControl(userId, amount);
    validateLimitOrThrow(userId, category, category, BigDecimal.ZERO, amount);
    expenseAnalysisService.handleExpenseAnalysis(userId, sharedExpenseRequest.confirmPasswordDto(), amount, ExpenseAnalysisMode.ADD);

    // ...build and save the expense...

    sharedWalletService.removeBalanceFromWallet(userId, expense.getAmount());
    sharedExpenseRepository.save(expense);

    largeExpenseNotificationService.handleLargeNotification(userId, expense);

    return new SharedExpenseResponse(expense.getId(), userId, createdByUsername);
}

Every one of those handle* calls is a settings-driven feature that can be toggled independently — spend limits, anomaly detection requiring a password, and large-expense email alerts — but the expense-adding flow itself doesn't know or care about the details of any of them. Each service checks its own toggle, does its own thing, and returns.

What This Taught Me

Model relationships, not just entities. Once I stopped thinking of shared account settings as "a setting on user A" and started thinking of them as "a setting on the pair (A, B)," a whole category of bugs (which side's toggle wins?) simply disappeared.

The outbox pattern pays for itself fast. Every place where a business action needs to also notify another service, wrapping it in outboxService.save(...) inside the same transaction means I never have to reason about "what if Kafka was down for that one request."

Idempotency isn't optional for event consumers. The existsByOwnerIdAndMemberId check in the deletion handler is three lines of code that turn "retry-safe" from a hope into a guarantee.

Thanks for reading!
My github:

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

Finovara is a personal finance platform designed to help users take full control of their money. The backend exposes a secure REST API that powers tracking of income and expenses, budget management, savings goals, and financial reporting — all wrapped in a bank-grade security model based on JWT authentication.

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

From Monolith to Microservices: Why I Redesigned Finovara's Architecture - Finovara

Marcin Parśniak — Sat, 06 Jun 2026 21:23:26 +0000

At some point, a monolith starts working against you.

In my case, Finovara was a single Spring Boot application handling everything (authentication, transactions, limits, piggy banks, notifications, activity logs, currency conversion)

The bigger it got, the harder it was to change anything without worrying about something else breaking.

So I broke it apart.

This post is about the first three pieces I extracted: the API Gateway, the activity-log-backend, and a shared module called contracts-backend.

The Old Structure

Everything lived in one Spring Boot app.

The activity log — which tracks everything a user does in the app (expenses added, limits changed, logins, account changes) — was tangled up with the core business logic. Adding a new type of activity meant touching the same codebase responsible for transactions, security, and everything else.

The New Structure

finovara-backend/
├── api-gateway/
├── activity-log-backend/
├── contracts-backend/
└── core-backend/

Four modules (there will be more). Each with a clear responsibility.

API Gateway

The gateway is the single entry point for every request coming from the frontend.

It runs on port 8888 with SSL enabled and uses Spring Cloud Gateway (WebFlux-based).

Routing is simple and declarative:

routes:
  - id: activity-log-backend
    uri: ${ACTIVITY_LOG_URL}
    predicates:
      - Path=/api/account-activity/**,/api/archive-activities/**

  - id: notification-backend
    uri: ${NOTIFICATION_BACKEND_URL}
    predicates:
      - Path=/api/notification-settings/**

  - id: core-backend
    uri: ${CORE_BACKEND_URL}
    predicates:
      - Path=/**

Activity log routes go to activity-log-backend. Notification routes go to notification-backend. Everything else falls through to core-backend.

The gateway also handles CORS centrally — https://localhost:5173 is the only allowed origin, with credentials support. No individual service needs to worry about CORS anymore.

One thing worth noting: the gateway uses use-insecure-trust-manager: true for the HTTP client. The services communicate over HTTPS internally, and during local development with self-signed certs this was the pragmatic solution.

contracts-backend

This is the shared kernel of the whole system.

It's a separate module — no business logic, no controllers, no database. Just shared code that multiple services depend on:

Kafka event records used between services
DTOs shared across service boundaries
Utility classes for extracting client data

For example, every activity event is a Java record defined here:

public record ExpenseActivityEvent(
        Long userId,
        ExpenseActivityType type,
        BigDecimal amount,
        ExpenseCategory category,
        BigDecimal previousAmount,
        ExpenseCategory previousCategory,
        LocalDateTime occurredAt
) {}

Same pattern for LoginActivityEvent, LimitActivityEvent, PiggyBankActivityEvent, RevenueActivityEvent, SettingsActivityEvent, AccountChangesActivityEvent.

The utility classes handle things like extracting the client's real IP behind a proxy:

public static String getClientIpAddress(HttpServletRequest request) {
    String xfHeader = request.getHeader("X-Forwarded-For");
    if (xfHeader == null) {
        return request.getRemoteAddr();
    }
    return xfHeader.split(",")[0];
}

And resolving location from IP using the ip-api.com API:

String url = "http://ip-api.com/json/" + ip;
RestTemplate restTemplate = new RestTemplate();
Map<String, Object> response = restTemplate.getForObject(url, Map.class);

Browser detection uses a User-Agent parser:

Client client = parser.parse(userAgent);
return client.userAgent.family;

All of this lives in contracts-backend so it can be reused by core-backend, activity-log-backend, or any future service without duplication.

activity-log-backend

This service handles everything related to user activity history.

When a user adds an expense, changes a limit, logs in, or modifies account settings — an event is published to Kafka by core-backend. The activity-log-backend consumes those events and persists them independently.

The consumer class listens to all activity topics:

@KafkaListener(topics = "activity.expense")
public void handleExpense(ExpenseActivityEvent event) {
    expenseActivityService.handleEvent(event);
}

@KafkaListener(topics = "activity.login")
public void handleLogin(LoginActivityEvent event) {
    loginActivityService.handleEvent(event);
}

@KafkaListener(topics = "activity.account-changes")
public void handleAccountChanges(AccountChangesActivityEvent event) {
    accountChangesActivityService.handleEvent(event);
}

@KafkaListener(topics = "user-account.deleted")
public void handleAccountDeleted(UserAccountDeletedEvent event) {
    deletableServices.forEach(service -> service.deleteByUserId(event.userId()));
}

Seven topics in total: activity.settings, activity.revenue, activity.piggybank, activity.login, activity.limit, activity.expense, activity.account-changes.

When a user deletes their account, core-backend publishes a user-account.deleted event. The activity service handles this by calling deleteByUserId on every service that implements UserDataDeletable. Clean and consistent.

Security section requires password confirmation

The login activity and account changes sections show sensitive data — IP address, browser, location. To access them, the user has to confirm their password first.

The activity service can't verify passwords itself. That logic lives in core-backend. So instead, it calls core-backend through a Feign client:

@FeignClient(name = "core-backend", url = "${core-backend.url}")
public interface CoreBackendClient {

    @PostMapping("/internal/verify-password")
    Void verifyPassword(@RequestHeader("X-User-Id") Long userId,
                        @RequestBody ConfirmPasswordDto dto);
}

This is the only synchronous call between activity-log-backend and core-backend. Everything else goes through Kafka.

core-backend

Everything that wasn't activity logging stayed here.

Authentication, transactions, limits, piggy banks, notifications, currency conversion, reports. The full business logic of Finovara — just without the activity tracking responsibility.

When something significant happens, core-backend publishes an event to Kafka and moves on. It doesn't know or care what activity-log-backend does with it.

What This Split Actually Solved

Isolation.

Activity logging can fail without touching transactions. The two failure domains are now separate.

Independent deployability.

I can update the activity service without touching core logic.

Cleaner codebase.

Each service has a clear reason to exist. The activity service handles activity. The gateway handles routing. The contracts module handles shared types.

What Was Painful

Kafka event design.

Getting the event records right took iteration. The contracts-backend module helps here — one place to change an event definition and both sides see it immediately.

Internal communication.

Deciding when to use Kafka vs Feign wasn't always obvious. The rule I settled on: async Kafka for everything event-driven, Feign only when the caller needs an actual response (like password verification).

Local SSL between services.

All services run HTTPS locally. The use-insecure-trust-manager in the gateway config is the result of that — not ideal, but it works for development.

This is still a work in progress. More services will be extracted from core-backend over time.

Thanks for reading!

If you want to follow Finovara's development, the source is on GitHub.

GitHub logo M4rc1nek / finovara-backend

Backend service for a personal finance management application

From Monolith to Microservices: Why I Redesigned Finovara's Architecture - Finovara

Marcin Parśniak — Sat, 06 Jun 2026 21:23:26 +0000

At some point, a monolith starts working against you.

In my case, Finovara was a single Spring Boot application handling everything (authentication, transactions, limits, piggy banks, notifications, activity logs, currency conversion)

The bigger it got, the harder it was to change anything without worrying about something else breaking.

So I broke it apart.

This post is about the first three pieces I extracted: the API Gateway, the activity-log-backend, and a shared module called contracts-backend.

The Old Structure

Everything lived in one Spring Boot app.

The New Structure

finovara-backend/
├── api-gateway/
├── activity-log-backend/
├── contracts-backend/
└── core-backend/

Four modules (there will be more). Each with a clear responsibility.

API Gateway

The gateway is the single entry point for every request coming from the frontend.

It runs on port 8888 with SSL enabled and uses Spring Cloud Gateway (WebFlux-based).

Routing is simple and declarative:

routes:
  - id: activity-log-backend
    uri: ${ACTIVITY_LOG_URL}
    predicates:
      - Path=/api/account-activity/**,/api/archive-activities/**

  - id: notification-backend
    uri: ${NOTIFICATION_BACKEND_URL}
    predicates:
      - Path=/api/notification-settings/**

  - id: core-backend
    uri: ${CORE_BACKEND_URL}
    predicates:
      - Path=/**

Activity log routes go to activity-log-backend. Notification routes go to notification-backend. Everything else falls through to core-backend.

The gateway also handles CORS centrally — https://localhost:5173 is the only allowed origin, with credentials support. No individual service needs to worry about CORS anymore.

contracts-backend

This is the shared kernel of the whole system.

It's a separate module — no business logic, no controllers, no database. Just shared code that multiple services depend on:

Kafka event records used between services
DTOs shared across service boundaries
Utility classes for extracting client data

For example, every activity event is a Java record defined here:

public record ExpenseActivityEvent(
        Long userId,
        ExpenseActivityType type,
        BigDecimal amount,
        ExpenseCategory category,
        BigDecimal previousAmount,
        ExpenseCategory previousCategory,
        LocalDateTime occurredAt
) {}

Same pattern for LoginActivityEvent, LimitActivityEvent, PiggyBankActivityEvent, RevenueActivityEvent, SettingsActivityEvent, AccountChangesActivityEvent.

The utility classes handle things like extracting the client's real IP behind a proxy:

public static String getClientIpAddress(HttpServletRequest request) {
    String xfHeader = request.getHeader("X-Forwarded-For");
    if (xfHeader == null) {
        return request.getRemoteAddr();
    }
    return xfHeader.split(",")[0];
}

And resolving location from IP using the ip-api.com API:

String url = "http://ip-api.com/json/" + ip;
RestTemplate restTemplate = new RestTemplate();
Map<String, Object> response = restTemplate.getForObject(url, Map.class);

Browser detection uses a User-Agent parser:

Client client = parser.parse(userAgent);
return client.userAgent.family;

All of this lives in contracts-backend so it can be reused by core-backend, activity-log-backend, or any future service without duplication.

activity-log-backend

This service handles everything related to user activity history.

The consumer class listens to all activity topics:

@KafkaListener(topics = "activity.expense")
public void handleExpense(ExpenseActivityEvent event) {
    expenseActivityService.handleEvent(event);
}

@KafkaListener(topics = "activity.login")
public void handleLogin(LoginActivityEvent event) {
    loginActivityService.handleEvent(event);
}

@KafkaListener(topics = "activity.account-changes")
public void handleAccountChanges(AccountChangesActivityEvent event) {
    accountChangesActivityService.handleEvent(event);
}

@KafkaListener(topics = "user-account.deleted")
public void handleAccountDeleted(UserAccountDeletedEvent event) {
    deletableServices.forEach(service -> service.deleteByUserId(event.userId()));
}

Seven topics in total: activity.settings, activity.revenue, activity.piggybank, activity.login, activity.limit, activity.expense, activity.account-changes.

Security section requires password confirmation

The login activity and account changes sections show sensitive data — IP address, browser, location. To access them, the user has to confirm their password first.

The activity service can't verify passwords itself. That logic lives in core-backend. So instead, it calls core-backend through a Feign client:

@FeignClient(name = "core-backend", url = "${core-backend.url}")
public interface CoreBackendClient {

    @PostMapping("/internal/verify-password")
    Void verifyPassword(@RequestHeader("X-User-Id") Long userId,
                        @RequestBody ConfirmPasswordDto dto);
}

This is the only synchronous call between activity-log-backend and core-backend. Everything else goes through Kafka.

core-backend

Everything that wasn't activity logging stayed here.

Authentication, transactions, limits, piggy banks, notifications, currency conversion, reports. The full business logic of Finovara — just without the activity tracking responsibility.

When something significant happens, core-backend publishes an event to Kafka and moves on. It doesn't know or care what activity-log-backend does with it.

What This Split Actually Solved

Isolation.

Activity logging can fail without touching transactions. The two failure domains are now separate.

Independent deployability.

I can update the activity service without touching core logic.

Cleaner codebase.

Each service has a clear reason to exist. The activity service handles activity. The gateway handles routing. The contracts module handles shared types.

What Was Painful

Kafka event design.

Getting the event records right took iteration. The contracts-backend module helps here — one place to change an event definition and both sides see it immediately.

Local SSL between services.

All services run HTTPS locally. The use-insecure-trust-manager in the gateway config is the result of that — not ideal, but it works for development.

This is still a work in progress. More services will be extracted from core-backend over time.

Thanks for reading!

If you want to follow Finovara's development, the source is on GitHub.

GitHub logo M4rc1nek / finovara-backend

Backend service for a personal finance management application

Building a Currency Converter in Spring Boot with Feign and NBP API - Finovara

Marcin Parśniak — Thu, 07 May 2026 20:47:57 +0000

Recently I added a new backend feature to Finovara — a currency conversion module powered by the public API from the National Bank of Poland (NBP).

The goal was to create a clean and scalable solution that could:

fetch real exchange rates
support multiple conversion strategies
handle external API failures properly
provide precise financial calculations

This feature became a really solid example of practical backend development with Spring Boot and OpenFeign.

Using Feign to Integrate the NBP API.

To communicate with the NBP API, I used OpenFeign.

The implementation is very clean and keeps the HTTP layer separated from the business logic.

@FeignClient(name = "nbp-api", url = "${nbp.api.url}")
public interface NbpApiClient {

    @GetMapping("/exchangerates/tables/A")
    List<NbpTableDto> getAllRates(@RequestParam("format") String format);
}

NBP provides public exchange rate tables in JSON format, which makes integration very straightforward.

DTO Mapping

To deserialize the response from the API, I used Java records.

@JsonIgnoreProperties(ignoreUnknown = true)
public record NbpTableDto(
        @JsonProperty("table")
        String tableType,

        @JsonProperty("no")
        String tableNumber,

        @JsonProperty("effectiveDate")
        String publishDate,
        @JsonProperty("rates")
        List<Rate> rates
) {
    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Rate(
            @JsonProperty("currency")
            String name,

            @JsonProperty("code")
            String currencyCode,

            @JsonProperty("mid")
            BigDecimal averageRate
    ) {
    }
}

I really like using records for DTOs because they keep the code lightweight, immutable, and easy to read.

Currency Conversion Service

The main logic lives inside the NbpService.

The service supports:

PLN → foreign currency
foreign currency → PLN
foreign currency → foreign currency


@Slf4j
@Service
@RequiredArgsConstructor
public class NbpService {

    @Value("${nbp.properties.scale}")
    private int scale;


    private static final RoundingMode ROUNDING_MODE = RoundingMode.HALF_UP;
    private final NbpApiClient nbpApiClient;

    public List<NbpTableDto> getAllRates() {
        try{
            return nbpApiClient.getAllRates("json");
        }catch (FeignException exception){
            log.error("Failed to fetch rates from NBP API", exception);
            throw new ServiceUnavailableException("Failed to get all rates", exception);
        }
    }

    public BigDecimal convertCurrencies(String fromCurrency, String toCurrency, BigDecimal amount, NbpConversionType conversionType) {
        if (fromCurrency.equalsIgnoreCase(toCurrency)) {
            return amount.setScale(scale, ROUNDING_MODE);
        }

        List<NbpTableDto.Rate> exchangeRates = fetchExchangeRates();

        return switch (conversionType) {
            case FROM_PLN -> convertFromPln(exchangeRates, toCurrency, amount);
            case TO_PLN -> convertToPln(exchangeRates, fromCurrency, amount);
            case FOREIGN_CURRENCIES -> convertBetweenForeignCurrencies(exchangeRates, fromCurrency, toCurrency, amount);
        };
    }

    private BigDecimal convertFromPln(List<NbpTableDto.Rate> exchangeRates, String toCurrency, BigDecimal amount) {
        BigDecimal toRate = findRateByCode(exchangeRates, toCurrency);
        return amount.divide(toRate, scale, ROUNDING_MODE);
    }

    private BigDecimal convertToPln(List<NbpTableDto.Rate> exchangeRates, String fromCurrency, BigDecimal amount) {
        BigDecimal fromRate = findRateByCode(exchangeRates, fromCurrency);
        return amount.multiply(fromRate).setScale(scale, ROUNDING_MODE);
    }

    private BigDecimal convertBetweenForeignCurrencies(List<NbpTableDto.Rate> exchangeRates, String fromCurrency, String toCurrency, BigDecimal amount) {
        BigDecimal fromRate = findRateByCode(exchangeRates, fromCurrency);
        BigDecimal toRate = findRateByCode(exchangeRates, toCurrency);
        BigDecimal amountInPln = amount.multiply(fromRate);
        return amountInPln.divide(toRate, scale, ROUNDING_MODE);
    }

    private BigDecimal findRateByCode(List<NbpTableDto.Rate> exchangeRates, String currencyCode) {
        return exchangeRates.stream()
                .filter(rate -> rate.currencyCode().equalsIgnoreCase(currencyCode))
                .findFirst()
                .map(NbpTableDto.Rate::averageRate)
                .orElseThrow(() -> new InvalidInputException("Unsupported currency: " + currencyCode));
    }

    private List<NbpTableDto.Rate> fetchExchangeRates() {
        List<NbpTableDto> tables = getAllRates();
        if (tables == null || tables.isEmpty()) {
            throw new InvalidInputException("Exchange rates are currently unavailable.");
        }
        return tables.getFirst().rates();
    }
}

What Was Costly

This wasn’t just a small feature addition.

It required:

integrating an external API with Feign
creating DTO mappings for NBP API responses
implementing multiple conversion strategies
handling financial precision correctly with BigDecimal
adding proper exception handling for external API failures
designing reusable conversion logic
validating unsupported currencies and invalid requests

Even relatively simple finance-related features become more complex once precision and reliability matter.

Things to Watch Out For

If you’re building something similar, there are a few important things to keep in mind.

Financial Precision

Never use double for currency calculations.

Using BigDecimal together with proper rounding modes is essential for predictable and safe financial calculations.

External API Failures

Public APIs can become unavailable at any moment.

Without proper exception handling and fallback logic, a simple API outage can break part of your application.

That’s why handling exceptions like:

FeignException

and providing meaningful fallback behavior is extremely important.

Validation

Always validate supported currency codes and incoming requests.

Without proper validation, invalid input can easily lead to unexpected runtime issues and broken conversion flows.

Testing

Currency conversion logic should always be covered with tests.

Small rounding inconsistencies or conversion mistakes can quickly become serious problems in finance-related systems.

Thanks for reading!

If you'd like to see Finovara development, check out my GitHub!

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

From Email to User ID: A Security-Driven Refactor in Spring Boot Backend - Finovara

Marcin Parśniak — Sat, 18 Apr 2026 09:26:52 +0000

At some point, a backend outgrows its initial assumptions.

In my case, that assumption was simple:
email = user identity

It worked fine early on. It was convenient, readable, and easy to query. But over time, it started to create real limitations—both in terms of features and security.

This post is about why I moved away from using email as the primary identifier, what had to change, and what improved as a result.

The Problem with Using Email as Identity

Initially, email was used everywhere:

in JWT subject
in database queries
across service layer logic

Typical example:

userRepository.findByEmail(email)

And in JWT:

.setSubject(user.getEmail())

This approach has one fundamental flaw:

Email is not a stable identifier.

The moment you want to support changing email, things start to break:

JWT tokens become inconsistent
existing sessions may become invalid
references across the system lose integrity

In practice, it blocks you from implementing a very basic feature: updating user email.

Why This Matters

Using a mutable field as identity introduces a few issues:

1. Tight coupling
Your entire system depends on a value that can change.

2. Inconsistent authentication
JWT subject no longer represents a stable user reference.

3. Limited extensibility
Features like:

email change
social login
account linking become harder to implement cleanly

The Refactor: Switching to User ID

The core idea was straightforward:

Use userId as the single source of identity across the system.

Email is now just a property of the user—not something the system relies on for identification.

Key Changes

1. JWT now stores user ID

.setSubject(user.getId().toString())
.claim("userId", user.getId())

This ensures:

the identifier is stable
it maps directly to the database
it doesn’t change over time

2. Extracting user ID from token

public Long extractUserId(String token) {
    Claims claims = extractAllClaims(token);

    Object userIdClaim = claims.get("userId");
    if (userIdClaim instanceof Number number) {
        return number.longValue();
    }
    if (userIdClaim instanceof String userIdText) {
        return Long.parseLong(userIdText);
    }

    return Long.parseLong(claims.getSubject());
}

This handles multiple formats and keeps backward compatibility with older tokens.

3. Authentication filter now works with ID

Before:

findByEmail(...)

After:

Long userId = jwtService.extractUserId(jwt);
User user = userRepository.findById(userId).orElse(null);

This removes ambiguity and avoids relying on user-controlled fields.

4. CustomUserDetails updated

private final Long id;
private final String email;

The important part is that ID is now always available in the security context.

5. Centralized access via SecurityUtils

public static Long getCurrentUserId() {
    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

    if (authentication == null || !authentication.isAuthenticated()) {
        throw new IllegalStateException("No authenticated user in security context");
    }

    Object principal = authentication.getPrincipal();

    if (principal instanceof CustomUserDetails userDetails) {
        return userDetails.getId();
    }

    if (principal instanceof String principalValue) {
        return Long.parseLong(principalValue);
    }

    throw new IllegalStateException("Unsupported principal type");
}

This becomes the standard way to access the current user across the application.

What Improved

More predictable authentication

User identity is now:

immutable
consistent across requests
independent of user input

Better security model

The system no longer relies on fields that users can change.
Every request resolves to a database ID, which must exist.

Easier feature development

Adding support for:

email change
multiple authentication methods
external providers

is now straightforward.

What Was Costly

This wasn’t a small refactor.

It required:

updating JWT generation and parsing
rewriting authentication filter logic
replacing findByEmail across the codebase
adjusting services and flows that depended on email

It’s the kind of change that touches a lot of code and needs to be done consistently.

Things to Watch Out For

If you’re considering a similar change:

Old tokens
Tokens using email may stop working. You may need to force re-authentication.

Partial refactors
Mixing email-based and ID-based logic will lead to subtle bugs.

Tests
Without proper test coverage, it’s easy to introduce regressions in authentication flow.

Thanks for reading!

If you'd like to see Finovara development, check out my GitHub!

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

How I Designed a Scalable Notification System with JSON Polymorphism in Spring Boot - Finovara

Marcin Parśniak — Thu, 16 Apr 2026 19:30:00 +0000

While working on my project Finovara, I recently implemented a flexible notification system that reacts to user actions — like reaching a savings goal in a piggy bank.

Instead of going with a rigid structure, I decided to build something extensible and future-proof.

🧠 The Problem

Users perform different actions in the system:

reaching a savings goal
completing financial milestones
(more coming soon…)

Each of these events should generate a notification, but with different payloads.

I didn’t want:

dozens of tables
messy conditional logic
tightly coupled notification handling

⚙️ The Approach

I used JSON polymorphism with Jackson to store notifications in a single table, while keeping type-specific structures.

Each notification implements a common interface:

public interface NotificationResponse {
    NotificationType type();
    LocalDate createdAt();
    String deduplicationKey();
}

And then I define specific types like this:

@JsonTypeName("PIGGY_BANK_GOAL_REACHED")
public record PiggyBankReachedDto(
        NotificationType type,
        LocalDate createdAt,
        PiggyBankGoalType goalType,
        String piggyBankName,
        Long piggyBankId,
        BigDecimal threshold
) implements NotificationResponse {

    @Override
    public String deduplicationKey() {
        return "%s:%d:%s:%s".formatted(type, piggyBankId, goalType, threshold);
    }
}

🧩 Generic Notification Engine

To avoid duplicating logic, I introduced a generic abstraction:

public abstract class ThresholdReachedService<E, C> implements NotificationCreator {
    protected static final BigDecimal REACHED_THRESHOLD = BigDecimal.valueOf(100);

    protected abstract List<E> fetchEntities(Long userId);

    protected abstract C calculate(E entity, Long userId);

    protected abstract BigDecimal getPercentage(C context);

    protected abstract NotificationResponse buildNotification(E entity, C context, Long userId);
    @Override
    public List<NotificationResponse> getNotifications(Long userId) {
        List<NotificationResponse> result = new ArrayList<>();

        for (E entity : fetchEntities(userId)) {
            C context = calculate(entity, userId);
            BigDecimal percentage = getPercentage(context);

            if (percentage.compareTo(REACHED_THRESHOLD) >= 0) {
                result.add(buildNotification(entity, context, userId));
            }
        }

        return result;
    }
}

This allows me to:

fetch domain entities
calculate progress
generate notifications only when a threshold is reached

💾 Persistence with Deduplication

One tricky part: avoiding duplicate notifications.

I solved it with a deduplicationKey:

.filter(dto -> !existingKeys.contains(dto.deduplicationKey()))
.filter(dto -> batchKeys.add(dto.deduplicationKey()))

This ensures:

no duplicates from previous runs
no duplicates within the same batch

🔄 Serialization Layer

Notifications are stored as JSON:

payload(toJson(dto))

and safely deserialized:

objectMapper.readValue(payload, NotificationResponse.class);

This gives me:

flexibility in adding new notification types
no schema changes needed
clean separation of concerns

✅ What I Gained

✔️ Extensible architecture
✔️ Clean domain separation
✔️ No schema migrations for new notification types
✔️ Easy to plug in new features

Thanks for reading, and check out my github!

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

Reducing Duplication in Email Notification Settings with an Abstract Service in Spring Boot - Finovara

Marcin Parśniak — Thu, 09 Apr 2026 19:59:16 +0000

When working on user notification settings in my Spring Boot project, I noticed a lot of duplicated logic across different email notification services

Each type of notification (password change, etc.) was doing almost the same thing:

loading the user
reading notification settings
updating a boolean flag
sending an email conditionally
logging activity

So I decided to refactor it using an abstract base service.

Before refactor (problem)

Every service contained similar logic like this:

User user = userManagerService.getUserByEmailOrThrow(email);
NotificationEmailSettings settings = user.getNotificationEmailSettings();

settings.setNotifyOnPasswordChange(dto.enabled());

And then duplicated email sending + activity logic across multiple services.

This led to:

duplicated code
inconsistent behavior risk
harder onboarding for new notification type

Solution: AbstractNotificationEmailService

I introduced a template-based abstract service that handles the shared workflow.

Now the base class looks like this:

@RequiredArgsConstructor
public abstract class AbstractNotificationEmailService {

    protected final UserManagerService userManagerService;
    protected final NotificationEmailSender notificationEmailSender;

    @Transactional
    public void saveEmailNotification(String email, NotificationEmailDto dto) {
        User user = userManagerService.getUserByEmailOrThrow(email);
        NotificationEmailSettings settings = user.getNotificationEmailSettings();

        boolean enabled = isEnabled(dto);
        applySetting(settings, enabled);

        handleActivity(email, enabled);
    }

    public NotificationEmailDto getEmailNotification(String email) {
        User user = userManagerService.getUserByEmailOrThrow(email);
        NotificationEmailSettings settings = user.getNotificationEmailSettings();

        return mapToDto(settings);
    }

    public void sendEmail(User user) {
        notificationEmailSender.sendIfEnabled(
                user,
                this::isNotificationEmailSettingsEnabled,
                this::sendEmailToUser
        );
    }

    protected abstract boolean isEnabled(NotificationEmailDto dto);

    protected abstract void applySetting(NotificationEmailSettings settings, boolean value);

    protected abstract boolean isNotificationEmailSettingsEnabled(NotificationEmailSettings settings);

    protected abstract NotificationEmailDto mapToDto(NotificationEmailSettings settings);

    protected abstract void sendEmailToUser(User user);

    protected void handleActivity(String email, boolean enabled) {
        // optional override
    }
}

Example implementation

Each notification type now only defines its own behavior.

Example: password change notification

@Service
public class NotifyPasswordChangeService extends AbstractNotificationEmailService {

    private final PasswordChangeEmailService passwordChangeEmailService;
    private final SettingsActivityService settingsActivityService;

    public NotifyPasswordChangeService(
            UserManagerService userManagerService,
            NotificationEmailSender notificationEmailSender,
            PasswordChangeEmailService passwordChangeEmailService,
            SettingsActivityService settingsActivityService
    ) {
        super(userManagerService, notificationEmailSender);
        this.passwordChangeEmailService = passwordChangeEmailService;
        this.settingsActivityService = settingsActivityService;
    }

    @Override
    protected boolean isEnabled(NotificationEmailDto dto) {
        return dto.enabled();
    }

    @Override
    protected void applySetting(NotificationEmailSettings settings, boolean value) {
        settings.setNotifyOnPasswordChange(value);
    }

    @Override
    protected boolean isNotificationEmailSettingsEnabled(NotificationEmailSettings settings) {
        return settings.isNotifyOnPasswordChange();
    }

    @Override
    protected NotificationEmailDto mapToDto(NotificationEmailSettings settings) {
        return new NotificationEmailDto(settings.isNotifyOnPasswordChange());
    }

    @Override
    protected void sendEmailToUser(User user) {
        passwordChangeEmailService.sendEmail(user);
    }

    @Override
    protected void handleActivity(String email, boolean enabled) {
        settingsActivityService.createSettingActivity(
                email,
                enabled ? SettingActivityStatus.ENABLED : SettingActivityStatus.DISABLED,
                SettingType.NOTIFICATION_PASSWORD_CHANGED
        );
    }
}

What improved

After this refactor:

Better structure: shared logic is in one place
Less duplication: no repeated boilerplate across services
Easier extension:new notification = just extend abstract class
More consistency: same flow for every notification type

Thanks for reading, if you want check my github!

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

Finovara - Building a Simple Chatbot in Spring Boot

Marcin Parśniak — Wed, 25 Mar 2026 16:37:24 +0000

Recently, I added a simple chatbot to my Finovara app that answers users’ finance-related questions.

No AI, no NLP libraries — just clean architecture, enums, and text files.

It works surprisingly well for the limited scope we need. Here’s how it’s built.

The Idea

The chatbot works like this:

A user asks a question.
The system normalizes the input.
It maps the question to a predefined entry.
The entry corresponds to a SmartReportType enum.
The enum is handled by a handler class.
The handler generates the actual response.

This makes the system:

Predictable
Easy to extend
Fast and lightweight

Core Architecture

The main entry point is:

  public String generateResponse(String email, String userQuestion) {
        User user = userManagerService.getUserByEmailOrThrow(email);

        SmartReportType type = smartReportQuestionService.getTypeFromQuestion(userQuestion);

        if (type == null)
            return "I’m not smart enough to answer this question. Please ask a question from the question book!";

        SmartReportHandler handler = handlers.get(type);

        if (handler == null) {
            return "Report type not supported";
        }

        return handler.generate(user.getId());
    }

Here’s what’s happening:

The question is mapped to a SmartReportType enum.
Each enum has its own handler.
The handler generates a response based on templates and user data.

This is basically a Strategy Pattern in action.

Mapping Questions to Enums

Instead of hardcoding questions in Java, they are stored in TXT files:

MONTH_SPENDING | how much did i spend this month
MONTH_SPENDING | monthly expenses
AVERAGE_DAY_SPENDING | average daily spending
EXPENSE_RATE | what percentage of my income is spent
SAVINGS_RATE | how much did i save

Loader Service:

questionMap.put(question, SmartReportType.valueOf(enumName));

Normalization:

private String normalize(String text) {
    return text.toLowerCase()
        .trim()
        .replace("?", "");
}

Thanks to this:

“How much did I spend?”
“how much did i spend”
“HOW MUCH DID I SPEND??”

all map to the same key.

Handlers: Business Logic

Each enum type has its own handler:

public interface SmartReportHandler {
    SmartReportType getType();
    String generate(Long userId);
}

Handlers are responsible for fetching user data and generating responses.

Example: Expense Rate

BigDecimal total = sumExpenses.multiply(BigDecimal.valueOf(100))
    .divide(sumRevenue, 2, RoundingMode.HALF_UP);

String template = templateService.getRandomResponse(SmartReportType.EXPENSE_RATE);
return template.replace("{amount}", total.toString());

Dynamic Responses (Templates)

Responses are stored in text files instead of being hardcoded:

You spent {amount} this month.
Your total expenses are {amount}.
Your savings rate is {amount}%.

Randomization makes replies feel less repetitive:

return responses.get(random.nextInt(responses.size()));

*Thanks for reading! *

If you’re curious to see the full project or try it yourself, check out the code on GitHub:

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

Deploying Finovara on Docker and fixing a critical bug.

Marcin Parśniak — Fri, 20 Mar 2026 21:35:33 +0000

I recently decided to move my Spring Boot app Finovara to Docker.

At first it was just supposed to be a small improvement to the setup.
In reality, it turned into a debugging session that took way longer than I expected.

Why I even bothered with Docker

There were a few reasons behind this:

I wanted more control over the environment
I needed a separate database (finovara-test) for automated tests
I was tired of manually setting everything up locally
and I wanted something closer to a real production setup

Initial setup

I started with a simple PostgreSQL container and connected my app to it.

Here’s a simplified version of what I used:

services:
  finovara-db:
    image: postgres:15
    container_name: finovara-db
    restart: always
    environment:
      POSTGRES_DB: finovara
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10

Dockerfile:

FROM eclipse-temurin:21-jdk
WORKDIR /app
COPY target/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

Everything started without issues.
Database was running, app connected, no errors.

So I thought I was done.

The moment things got weird

I made some changes in the app, rebuilt everything, ran it again and nothing changed.

same responses
same data
same behavior

At this point I was pretty sure I messed something up.

What I thought vs what it actually was

My first guess was Docker caching.
Seemed like the obvious explanation.

But after digging a bit more, it turned out to be something else entirely.

The app was connecting to a completely different database than I expected.

Everything looked correct:

same DB name
same user
same config

So from the outside it looked like everything was fine, but I was basically working on one database and checking another.

Fixing it

The fix wasn’t one single thing, more like a combination of small adjustments:

I changed the password in my .env file
I changed the port, because something else was already using 5432
I cleaned up and adjusted the docker-compose config
and most importantly, I actually verified which database the app connects to

After that, everything finally made sense again and changes started showing up immediately.

Thanks for reading and visit my github!

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection
💸 Income & Expense Tracking — full CRUD for financial operations with category tagging
📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports
🏦…

View on GitHub

Liquibase in Spring Boot – Developer's Guide

Marcin Parśniak — Tue, 10 Mar 2026 08:05:12 +0000

Liquibase in Spring Boot – Developer's Guide

Managing database schema changes can seem simple at first… until it isn’t. A quick ALTER TABLE here and there might work with one developer, but once you have multiple environments—dev, staging, prod—things get messy fast.

This is where Liquibase comes in.

In this guide, I’ll walk you through:

What Liquibase is and why it matters
Setting it up in Spring Boot
Writing migrations safely
Managing different environments

What is Liquibase?

Liquibase is essentially Git for your database schema. Instead of running SQL scripts manually and hoping everyone runs them correctly, you define changes in a structured format and Liquibase tracks which ones have been applied.

Example XML changeset:

<changeSet id="add-phone-number" author="dev">
    <addColumn tableName="users">
        <column name="phone_number" type="varchar(20)"/>
    </addColumn>
</changeSet>

Liquibase keeps track of applied migrations in a table called DATABASECHANGELOG, ensuring:

Changes are applied only once
Order is maintained
Rollbacks are possible

Why use Liquibase with Spring Boot?

Some key benefits:

Consistent environments – dev, staging, and prod stay in sync
Migration history – see who changed what and when
Automatic migrations – Spring Boot can run them on startup
Rollbacks – undo changes safely if needed

Adding Liquibase to your project

Maven:

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

Gradle:

implementation 'org.liquibase:liquibase-core'

Spring Boot will automatically detect Liquibase and run migrations.

Configuration

In application.yml (safe YAML formatting):

spring:
  liquibase:
    change-log: "classpath:/db/changelog/changelog.xml"
    contexts: "dev"

Typical project structure:

resources
 └ db
    └ changelog
        └ changelog.xml

Master changelog with multiple changesets

Instead of separate XML files, you can put all changesets in a single file: changelog.xml

<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                   http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd">

    <changeSet id="create-users" author="you">
        <createTable tableName="users">
            <column name="id" type="bigint">
                <constraints primaryKey="true"/>
            </column>
            <column name="email" type="varchar(255)">
                <constraints nullable="false"/>
            </column>
            <column name="created_at" type="timestamp"/>
        </createTable>
    </changeSet>

    <changeSet id="add-email-index" author="you">
        <createIndex indexName="idx_users_email" tableName="users">
            <column name="email"/>
        </createIndex>
    </changeSet>

    <changeSet id="add-phone-column" author="you">
        <addColumn tableName="users">
            <column name="phone_number" type="varchar(20)"/>
        </addColumn>
        <rollback>
            <dropColumn tableName="users" columnName="phone_number"/>
        </rollback>
    </changeSet>

    <changeSet id="insert-test-data" author="you" context="you">
        <insert tableName="users">
            <column name="id" valueNumeric="1"/>
            <column name="email" value="test@example.com"/>
        </insert>
    </changeSet>

</databaseChangeLog>

Using SQL instead of XML

You can also write all changesets in a single formatted SQL file:

-- liquibase formatted sql
-- changeset dev:create-users
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP
);

-- changeset dev:add-email-index
CREATE INDEX idx_users_email ON users(email);

-- changeset dev:add-phone-column
ALTER TABLE users ADD COLUMN phone_number VARCHAR(20);
-- rollback: ALTER TABLE users DROP COLUMN phone_number;

Best practices

Never edit executed migrations – migrations are immutable
One changeset = one change – separate tables, columns, and indexes
Number your files if using multiple files – avoids Git conflicts
Test locally – drop the DB, run the app, ensure migrations work from scratch
Be careful on production – avoid ALTER COLUMN TYPE, DROP COLUMN, or NOT NULL on large tables

Liquibase vs Flyway

Feature	Liquibase	Flyway
XML/YAML/JSON	✔	✖
SQL	✔	✔
Rollback	✔	limited

Flyway is simpler but Liquibase is more flexible for enterprise setups.

Conclusion

Liquibase is a lifesaver for keeping database schema consistent across environments. Stick to the golden rules:

immutable migrations
one change per changeset
test migrations locally

Thanks for reading!

Revenue test (JUnit5) - Finovara

Marcin Parśniak — Sat, 07 Mar 2026 10:56:13 +0000

Hello!

After the latest update to my project, I decided it was the perfect time to finally start writing tests for Finovara.

So far, I've written tests for the main methods.
On average, I run 2-3 tests per method, which seems like a good compromise. I cover both the happy path and a few edge cases and alternate flows—basically, I try to make sure everything works as expected, regardless of the situation.

Overall, I'm aiming for 70-80% code coverage, though this may change as I add more tests and improve what I already have.

Example of a simple test:

@Test
void shouldAddRevenueSuccessfully() {
        RevenueDTO dto = new RevenueDTO(null, null, new BigDecimal("100"), RevenueCategory.SALARY, null, "test income");
        String email = "test@test.com";
        User user = new User();

        when(timeConfig.clock()).thenReturn(Clock.systemDefaultZone());
        when(userManagerService.getUserByEmailOrThrow(email)).thenReturn(user);

        revenueService.addRevenue(dto, email);

        verify(walletService).addBalanceToWallet(email, dto.amount());
        verify(revenueActivityService).createRevenueActivity(eq(email), eq(RevenueActivityType.ADDED_REVENUE), any(Revenue.class));
        verify(revenueRepository).save(any(Revenue.class));
        verify(revenueScoringService).recalculateScore(email);
        verify(autoPaymentsService).handleRevenuePiggyBankAutomation(email, dto.amount(), AutoPaymentsMode.APPLY);
    }

Next, I plan to write expense tests. I'll see how it goes

Thanks for reading, and please visit my GitHub:

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

Backend REST API for a personal finance management application built with Java 25 and Spring Boot 4.

📖 About the Project

Finovara is a personal finance platform designed to help users take full control of their money. The backend exposes a secure REST API that powers tracking of income and expenses, budget management, savings goals, and financial reporting — all wrapped in a bank-grade security model based on JWT authentication.

The application is designed with scalability in mind and is fully containerized via Docker, with separate production and test database environments managed through Docker Compose.

🎯 Key Features

🔐 Authentication & Authorization — JWT-based stateless security with Spring Security; access and refresh token flow with device/user-agent detection

💸 Income & Expense Tracking — full CRUD for financial operations with category tagging

📊 Statistics & Reports — aggregated financial summaries, spending trends, and exportable PDF reports

🏦…

View on GitHub

User Notification Settings - Finovara

Marcin Parśniak — Thu, 05 Mar 2026 22:35:56 +0000

Hello everyone!

In the latest update to Finovara,
I implemented user notification settings.
This feature allows users to decide whether they want to receive email notifications for important account events.

What this feature does

Users can now enable or disable notifications for important events happening in their account.

When notifications are enabled and the user:

changes their password
changes username
deleted account

the system will send an email notification to the address assigned to his account informing his of the change.

Example of mail sending method:

 @Async
    public void sendEmail(User user, String subject, String templatePath, String username, String email) {
        try {
            MimeMessage message = javaMailSender.createMimeMessage();
            MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");

            helper.setTo(user.getEmail());
            helper.setFrom("Finovara <" + senderAddress + ">");
            helper.setReplyTo(senderAddress);
            helper.setSubject(subject);

            String html = loadTemplate(templatePath, username, email);
            helper.setText(html, true);

            javaMailSender.send(message);

        } catch (Exception e) {
            throw new RuntimeException("Failed to send email", e);
        }
    }

Example loadTemplate:

 private String loadTemplate(String templatePath, String username, String email) {
        try {
            ClassPathResource resource = new ClassPathResource(templatePath);
            try (InputStream inputStream = resource.getInputStream()) {
                String html = new String(inputStream.readAllBytes(), StandardCharsets.UTF_8);

                if (username != null) {
                    html = html.replace("{{username}}", username);
                }
                if (email != null) {
                    html = html.replace("{{email}}", email);
                }
                return html;
            }
        } catch (Exception e) {
            throw new RuntimeException("Failed to load email template", e);
        }
    }

Thanks for reading!

I encourage you to take a look at the process of creating the Finovara application at: https://github.com/M4rc1nek/finovara-backend

DEV Community: Marcin Parśniak

Building Shared Accounts in Finovara

The Core Idea: ownerId + memberId, Not a Shared User Table

Part 1: The Invitation Flow

Sending the Invitation — and Firing Off Three Different Events

Accepting an Invitation Creates the Shared Account — and Cascades Four More Events

Part 2: Settings That Belong to a Pair, Not a User

Part 3: Deleting a Shared Account Without Losing Money

Idempotency First

Refunding Fairly When Both Sides Contributed Differently

Cleanup and Cache Eviction Are Separate Concerns

Wiring It All Into the Expense Flow

What This Taught Me

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

📖 About the Project

🎯 Key Features

From Monolith to Microservices: Why I Redesigned Finovara's Architecture - Finovara

The Old Structure

The New Structure

API Gateway

contracts-backend

activity-log-backend

Security section requires password confirmation

core-backend

What This Split Actually Solved

What Was Painful

GitHub logo M4rc1nek / finovara-backend

Backend service for a personal finance management application

From Monolith to Microservices: Why I Redesigned Finovara's Architecture - Finovara

The Old Structure

The New Structure

API Gateway

contracts-backend

activity-log-backend

Security section requires password confirmation

core-backend

What This Split Actually Solved

What Was Painful

GitHub logo M4rc1nek / finovara-backend

Backend service for a personal finance management application

Building a Currency Converter in Spring Boot with Feign and NBP API - Finovara

Using Feign to Integrate the NBP API.

DTO Mapping

Currency Conversion Service

What Was Costly

Things to Watch Out For

Financial Precision

External API Failures

Validation

Testing

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

📖 About the Project

🎯 Key Features

From Email to User ID: A Security-Driven Refactor in Spring Boot Backend - Finovara

The Problem with Using Email as Identity

Why This Matters

The Refactor: Switching to User ID

Key Changes

1. JWT now stores user ID

2. Extracting user ID from token

3. Authentication filter now works with ID

4. CustomUserDetails updated

5. Centralized access via SecurityUtils

What Improved

More predictable authentication

Better security model

Easier feature development

What Was Costly

Things to Watch Out For

M4rc1nek / finovara-backend

Backend service for a personal finance management application

💰 Finovara — Backend

📖 About the Project

🎯 Key Features

How I Designed a Scalable Notification System with JSON Polymorphism in Spring Boot - Finovara

🧠 The Problem

The Core Idea: `ownerId` + `memberId`, Not a Shared User Table