Coder Legion - Recent posts tagged spring-boot

The Legacy Report Was Going Away. The Agent Still Needed the Answer.

Mon, 26 Oct 2026 04:08:02 +0000

An anonymized banking modernization case study about replacing SAS-backed operational reports with APIs that agents could use in Salesforce.

Imagine an agent opening a fraud or exception report during a customer call. The report appears in a legacy system, but the agent’s real task is to make a timely, authorized decision. If the system is retired and the same answer becomes slow, incomplete, or visible to the wrong person, the migration has failed—even if the new application looks better.

That was the challenge in a banking modernization program I worked on. Operational and business reporting functionality hosted on SAS needed to move into a Salesforce-centered workflow. My responsibilities included designing Spring Boot GET APIs for several report domains, connecting the service to Snowflake, applying agent role-based access, and exposing the endpoints to the Salesforce team. The architecture below is deliberately simplified; it describes the engineering pattern without disclosing internal systems or customer data.

First, migrate the decision—not the screen

A legacy report often contains more than a table. It can encode filters, calculations, refresh timing, exception definitions, and the habits people have built around it. Copying its columns into a new UI does not prove that an agent receives the same answer.

For each report, the useful questions were: Who uses it? Which decision does it support? What does each field mean? How fresh must it be? What should happen when the data is missing? These questions turn a screen replacement into a contract that the new service can implement and test.

An example is an exception report. A row count can match while the underlying definition of “open” changes, or a date filter shifts at midnight in a different time zone. The result looks plausible, but an agent may follow up on the wrong cases. A migration test therefore needs representative records and business-rule comparisons, not only a schema check.

Put a stable API between Salesforce and reporting data

We used RESTful GET endpoints to give the Salesforce experience a focused way to request report data. A service layer can validate inputs, apply business rules, authorize the caller, query Snowflake, and return a consistent response contract. It also gives the UI team a stable interface while the data or report logic evolves behind it.

Salesforce documents a request-and-reply integration pattern for user actions that call an external system and wait for the result. That pattern is useful for interactive reporting, but it makes latency and failure behavior part of the user experience. A timeout is not an empty report. The API should distinguish “no matching records” from “the source was unavailable,” use bounded queries and pagination where appropriate, and make error states clear enough for the UI to handle.

This service boundary also limits how much reporting logic leaks into the frontend. The API should expose business concepts the agent understands rather than Snowflake table names or a direct translation of old SAS implementation details.

Access control must follow the data all the way through

“The agent is signed into Salesforce” is only the start of an authorization decision. The backend still needs to know which report and which records that agent may access. Role checks at the API boundary protect the endpoint; data-scoped controls protect the result set. The two should agree, and denied access should be tested as carefully as successful access.

Snowflake supports row access policies that determine which rows a query returns. They are one possible defense in depth, subject to the organization’s roles and policy design. They also affect query behavior and performance, so access rules should be validated with realistic report requests. The point is broader than a particular Snowflake feature: a correct report returned to the wrong role is a production defect.

For a banking workflow, logs and traces also need restraint. A useful audit trail records who requested which report, when, and whether it succeeded. It does not need to dump sensitive report contents into application logs.

Prove the new path under production-like conditions

Functional tests answer whether the endpoint returns the right data for a known case. They do not answer whether a team of agents can use it at the same time on a busy morning. We developed performance tests with JMeter and Gatling to exercise the services against SLA requirements under load.

A meaningful test model includes the report mix, concurrent users, query sizes, authorized and unauthorized requests, and the effect of a slow data source. Measure end-to-end response time from the agent-facing API, not just the time taken by one SQL query. Check the long tail as well as the average. If a report is large, test pagination and the cost of repeated requests. If a dependency fails, verify that the service fails clearly and recovers.

I would also treat the cutover as a comparison exercise: sample the same business cases through the legacy and new paths, explain any differences, and have report owners validate them. Where old behavior was wrong, document the intended correction explicitly. Otherwise a “fixed” report can look like an unexplained regression to the people using it.

What this kind of migration teaches

The visible technology changes from SAS reports to Salesforce screens, Spring Boot APIs, and Snowflake queries. The hard part is preserving the meaning, access, and timing of the answer that an agent needs.

The reusable sequence is straightforward: inventory the decisions supported by each report; define the API contract and data semantics; enforce access at the service and data layers; compare old and new results; test peak traffic and failure modes; then cut over with clear ownership of discrepancies. That is how a platform retirement becomes a reliable workflow change instead of a prettier route to the wrong answer.

What has been the hardest part of a legacy reporting migration in your experience: report logic, data quality, access control, or cutover?

References

Salesforce, Integration Patterns
Snowflake, Understanding row access policies
Apache JMeter, User's Manual
Gatling, Documentation

Spring Boot Authentication Boilerplate: From JWT Basics to Production-Ready Auth

Sun, 20 Sep 2026 16:50:00 +0000

Starting a new Spring Boot project usually feels great.

You create the project, add a few dependencies, write your first controller...

Then authentication enters the chat.

Suddenly you're configuring:

Spring Security
JWT access tokens
refresh tokens
roles and permissions
password hashing
exception handling
database migrations

Three hours later, your original feature still has exactly zero lines of code.

Congratulations. You built authentication again.

The auth code isn't the interesting part

Most applications need roughly the same authentication foundation.

Return an access token.

Refresh it safely.

Protect endpoints.

Check roles.

Logout.

Maybe add passkeys, OAuth, account recovery, or multiple sessions later.

None of this is particularly unique to your SaaS, internal tool, API, or side project.

But we keep rebuilding it.

I was doing the same thing with my Spring Boot projects, so I eventually turned that repeated setup into AuthKit.

AuthKit Lite

AuthKit Lite is the free and open-source version.

It gives you a working Spring Boot authentication foundation with:

JWT access tokens
rotating refresh tokens
Spring Security
role-based authorization
BCrypt passwords
optional WebAuthn passkeys
Flyway migrations
H2 for instant local testing
MySQL support
integration tests
a browser-based API testing page

The goal is simple:

Clone → run → test the APIs → start building your application.

git clone https://github.com/buildbasekit/AuthKit-Lite.git
cd AuthKit-Lite
./mvnw spring-boot:run

Then open:

http://localhost:8080/api-test

No Docker ceremony.

No spending your evening creating JWT filters for the 17th time.

No pretending you'll "clean up the auth code later."

You can find AuthKit Lite here:

https://buildbasekit.com/boilerplates/authkit-lite/

When Lite isn't enough

Basic authentication is enough for many projects.

But production applications often grow into things like:

email verification
password recovery
multiple user sessions
session revocation
refresh-token replay protection
OAuth2 / OIDC
account linking
magic links
passkeys
account lifecycle handling

That is where AuthKit Pro comes in.

It takes the same idea further: provide the authentication foundation while keeping the application-specific business logic in your application.

The important part for me was avoiding a giant framework that tries to own the entire application.

Auth should be infrastructure.

Not your new hobby.

AuthKit Pro is here:

https://buildbasekit.com/boilerplates/authkit-pro

Lite or Pro?

The easiest way to think about it:

AuthKit Lite

Use it when you need a clean Spring Boot authentication starting point or want to understand and extend the implementation yourself.

It's free and open source.

AuthKit Pro

Use it when the project needs more complete authentication flows and production-focused session and account lifecycle features.

Both are source-code foundations.

You still own the application.

You can change the architecture.

You can remove features.

You can add your own authorization rules.

And your business logic doesn't have to live inside somebody else's authentication service.

Why a boilerplate?

I'm not trying to eliminate authentication decisions.

You still need to decide things like:

token lifetimes
authorization rules
production secrets
rate limiting
monitoring
application-specific permissions

A boilerplate just means you don't have to start those decisions from an empty SecurityConfig.java.

That's the part I wanted to solve.

Because there are much more interesting bugs waiting for us in the actual product.

AuthKit Lite — Free & Open Source

https://buildbasekit.com/boilerplates/authkit-lite/

AuthKit Pro — Production-Focused

https://buildbasekit.com/boilerplates/authkit-pro

Built with Spring Boot and Spring Security.

If you're building Spring Boot APIs, I'd also be interested to know:

Do you rebuild authentication for every project, maintain your own starter, or use an external identity provider?

AI Can Write Your Backend—But It Shouldn’t Rebuild the Foundation Every Time

Fri, 12 Jun 2026 17:16:39 +0000

AI can generate a Spring Boot controller in seconds. It can scaffold entities, repositories, services, security filters, validation, and tests before you finish describing the feature.

That speed looks transformative—until every new project starts with the same prompts:

Add JWT authentication
Add refresh tokens
Add role-based access control
Configure Spring Security
Add global exception handling
Add request validation
Add file uploads
Add storage integration
Fix the generated architecture
Fix the tests after the architecture changes

At that point, AI is not accelerating product development. It is helping you repeatedly rebuild infrastructure your team has already solved.

The more effective workflow is to start with a stable backend foundation and use AI to build the product-specific layer on top of it.

That gives the coding agent real context, keeps architectural decisions consistent, reduces prompt size, and limits the amount of generated code your team must review.

A. The Wrong Way to Measure AI Development Speed

A common mistake is measuring AI productivity by how quickly code appears.

A prompt produces 20 files in two minutes, so the workflow feels fast. But generated output is only the first stage of delivery. The code still needs to be understood, reviewed, integrated, secured, tested, and maintained.

For backend systems, the review cost can be substantial because the generated files are interconnected.

Authentication affects authorization. Authorization affects endpoints. Endpoints depend on DTOs, services, repositories, validation, and exception handling. File operations may depend on authentication, ownership, metadata, and storage-provider configuration.

A single inconsistency can break the entire flow.

The better metric is not time to generated code. It is time to a verified product feature.

That distinction changes how AI should be used.

B. Why Rebuilding Backend Infrastructure With AI Creates Drift

Most backend applications need a familiar set of capabilities before product development begins:

user registration and login
password hashing
access and refresh tokens
protected endpoints
roles and permissions
request validation
consistent API errors
file upload and download APIs
storage abstractions
automated tests
environment and security configuration

These capabilities matter, but they are rarely the reason a customer buys the product.

Your customers care about the workflow your application enables. They care about the data it organizes, the task it automates, the integration it provides, or the operational problem it removes.

They do not care that your team generated another custom JWT filter.

1. Separate prompts create separate architectural decisions

When authentication, uploads, validation, and error handling are generated through different prompts, the implementation can gradually lose consistency.

Typical symptoms include:

controllers using different response formats
services following different naming conventions
repositories being accessed directly from unrelated layers
duplicate DTOs representing the same data
security rules that do not match newly generated routes
token handling duplicated across filters and services
file ownership checks implemented differently across endpoints
tests that require different setup patterns for each feature

Each generated change may look reasonable in isolation. The system becomes difficult to maintain because the decisions do not form one coherent architecture.

2. Every correction expands the prompt

Once the code drifts, future prompts become larger:

Use the existing response wrapper, except for the upload controller. Keep the current token service, but do not copy the old refresh-token logic. Follow the package structure used by the billing module, not the user module. Do not modify the security filter because another feature depends on it.

This is not an efficient agent workflow. It is architectural debt being converted into prompt context.

3. Security code has a high verification cost

Generated security code can be syntactically valid and still be unsafe.

A Spring Security configuration may accidentally expose a route. A refresh-token flow may fail to revoke old sessions. A file endpoint may authenticate users without checking file ownership. A validation rule may exist at the controller boundary but be bypassed internally.

AI can help implement security-sensitive code, but it does not remove the need for human review and negative-path testing.

The strategic move is to reduce how often that critical infrastructure must be regenerated.

C. What the Backend Foundation Should Already Provide

A reusable backend foundation should solve repeated infrastructure while leaving product behavior open for extension.

It should not be a collection of copied snippets. It should be a working, documented application with clear boundaries.

1. Authentication and token lifecycle

The project should already define how registration, login, passwords, access tokens, refresh tokens, logout, expiration, and authentication failures work.

The important part is not merely having JWT support. The entire lifecycle must be consistent.

2. Authorization

Roles and permissions should be enforced through a predictable mechanism, such as route-level or method-level authorization.

Product code should not be filled with scattered checks such as:

if (user.getRole().equals("ADMIN")) {
    // perform action
}

The authorization model should be explicit enough that both developers and coding agents know how to protect a new feature.

3. Validation and exception handling

Request validation should follow one standard, and API errors should have one recognizable structure.

For example, a client should not receive three unrelated error shapes depending on whether the failure came from a controller, service, or security filter.

Consistency improves frontend integration, automated testing, logging, and AI-generated extensions.

4. File handling and storage boundaries

File systems become complicated quickly. A production-oriented design must consider:

ownership
access control
allowed file types
size limits
naming
metadata
streaming
deletion
retention
local or cloud storage
public versus private delivery

Product services should not depend directly on S3, local disk paths, or another storage vendor. They should depend on a storage boundary that can be replaced or extended.

5. Clear application layers

The application should communicate where each responsibility belongs:

src/main/java/com/example/app/
├── controller/
├── service/
├── security/
├── model/
├── repository/
├── dto/
├── exception/
└── config/

The exact folder names are not the key issue. Predictable ownership is.

Controllers should handle HTTP concerns. Services should own business workflows. Repositories should handle persistence. Security should establish identity and access. Storage integrations should remain behind a focused abstraction.

6. A usable testing strategy

The project should make it practical to test new features without rebuilding unrelated infrastructure for every test.

That means having examples for:

service tests
authenticated endpoint tests
role-based authorization tests
validation failures
repository integration tests
file-access and ownership tests

An AI agent produces better tests when it can follow an existing test pattern.

D. A Better AI-Assisted Backend Workflow

The following workflow shifts AI from infrastructure generator to product implementation partner.

1. Begin with a known backend foundation

For product delivery, an empty repository is usually the least efficient starting point.

Use a backend foundation that already implements and documents the repeated concerns. BuildBaseKit currently provides several Spring Boot starting points:

AuthKit-Lite for JWT authentication, refresh tokens, and role-based access
FiloraFS-Lite for lightweight local file-storage APIs
FiloraFS-Pro for authentication, S3 integration, file management, and streaming workflows

The objective is not to avoid understanding backend infrastructure. The objective is to avoid paying the implementation and verification cost every time a new product starts.

2. Verify the baseline before extending it

Before asking an AI agent to make changes, run the project and verify the existing flows.

Confirm that these behaviors work:

registration
login
access-token authentication
refresh-token rotation or renewal
protected routes
role restrictions
validation errors
global exception responses
file upload and retrieval
existing automated tests

This gives the team a known-good baseline.

Without a baseline, a later failure becomes harder to diagnose. The issue may come from the original foundation, the generated feature, or the interaction between both.

3. Put architectural context inside the repository

An AI agent should not have to reverse-engineer the project rules from scratch during every task.

Useful repository documents include:

AGENTS.md
ARCHITECTURE.md
AI_RULES.md
CONTRIBUTING.md
AGENT_CONTRIBUTING.md

These files should answer practical questions:

Which layer owns business logic?
How are DTOs named?
What API response format is required?
Which authentication flows must remain unchanged?
How should new permissions be implemented?
Which commands run unit and integration tests?
What files should not be modified?
What must pass before a task is complete?

BuildBaseKit's AI-ready project foundations use repository-level instructions to give coding agents this context before they edit the application.

The repository then becomes more than source code. It becomes the operating model for both human and AI contributors.

4. Request one bounded product change

Broad prompts create broad patches.

A prompt such as this gives the model too much control:

Build a complete secure Spring Boot backend with JWT authentication, refresh tokens, roles, validation, exception handling, file uploads, S3 storage, and tests.

A bounded prompt is much more effective:

Add an organization invitation endpoint using the existing authentication, validation, exception, and email patterns. Only organization admins can invite members. Add service and endpoint tests. Do not modify the token flow.

Other strong examples include:

Add admin-only file approval using the current role annotations and file metadata service.

Implement subscription cancellation inside the existing billing module. Preserve the current controller response format.

Add an audit event when a user deletes a file. Follow the existing event-publishing pattern and include tests.

These requests are easier to review because the desired behavior and the protected boundaries are explicit.

5. Review the patch as a change, not as a new system

A stable foundation allows the generated output to remain small.

Review can focus on questions such as:

Does the new code follow the existing architecture?
Is authorization enforced at the correct boundary?
Are ownership and tenant checks present?
Does the feature reuse existing validation and error handling?
Are database operations safe and transactional where needed?
Do tests cover unauthorized and invalid requests?
Did the agent modify unrelated infrastructure?

This is significantly more efficient than reviewing a newly invented security and storage architecture for every feature.

6. Test the business behavior

Suppose the new feature is organization invitations.

The useful test cases are now focused:

an authorized admin can create an invitation
a regular member cannot create an invitation
an invitation belongs to the correct organization
duplicate invitations are handled correctly
expired invitations cannot be accepted
invalid email addresses return the standard validation response
unauthenticated requests are rejected
the response follows the existing API contract

The team is testing the feature instead of simultaneously debugging JWT parsing, route configuration, persistence setup, and business logic.

E. Why This Workflow Uses Fewer Tokens

A large prompt often repeats information the repository should already contain:

technology stack
package structure
authentication requirements
token behavior
role definitions
validation conventions
error response shape
file-storage rules
testing expectations

When those decisions already exist in code and documentation, the prompt can describe only the change.

Compare these two requests.

Infrastructure-first prompt:

Generate JWT authentication for Spring Boot with refresh tokens, role-based authorization, validation, exception handling, and secure file uploads.

Foundation-first prompt:

Add a team invitation endpoint using the existing authentication and validation patterns.

The second request is smaller, but token reduction is not the only advantage.

It should also result in:

fewer generated files
fewer architectural decisions
a smaller review surface
fewer opportunities for unrelated regressions
more focused tests
easier rollback

The highest-value optimization is reducing the size and uncertainty of the change.

F. Why Existing Context Improves Generated Code

A blank repository gives the agent maximum freedom. That is often presented as an advantage, but for production systems it creates unnecessary risk.

The model must invent:

the package structure
naming rules
service boundaries
DTO patterns
API responses
exception types
token handling
permission enforcement
persistence conventions
test setup

An existing project turns those open decisions into constraints.

Constraints make the output more predictable.

An agent can inspect a current feature, identify the controller–service–repository pattern, and implement the next feature in the same way. It can copy the structure without copying the business logic.

That is the core principle behind AI-ready architecture:

Do not ask the agent to make every decision. Give it a system in which the important decisions have already been made.

G. Common Failure Modes

1. Regenerating authentication for each application

Authentication is repetitive and security-sensitive. Reuse a reviewed implementation and customize only the behavior the product actually requires.

2. Adding uploads without defining access rules

A file upload endpoint is not complete when a file reaches disk or S3.

Before implementation, define:

who owns the file
who may read it
who may delete it
allowed formats
maximum size
whether it is public or private
how metadata is stored
how downloads are authorized

3. Mixing business rules with Spring Security

Security should identify the caller and enforce access boundaries. Product services should implement the workflow.

When business behavior is buried inside filters or security configuration, both the code and the generated extensions become harder to reason about.

4. Trusting plausible generated security code

Security code often looks convincing. That is not evidence that it is correct.

Review route coverage, permission checks, token expiration, refresh behavior, logout semantics, CORS, CSRF assumptions, and error handling. Test unauthorized and cross-tenant access explicitly.

5. Sending one massive implementation prompt

A large prompt encourages the agent to create a large, tightly coupled patch.

Split the work into independently verifiable units. A smaller patch is easier to understand, test, revert, and maintain.

6. Measuring generated lines instead of delivered value

More generated code can mean more review work.

Measure:

time to a working feature
defect rate
regression rate
review time
test coverage
architectural consistency
security findings

Those metrics reflect delivery quality. Lines of code do not.

H. When Building From Scratch Is Still the Right Choice

A reusable foundation is not always the correct answer.

Building the infrastructure yourself makes sense when:

your primary goal is learning Spring Security or storage internals
the application has unusual authentication requirements
the project is governed by specialized compliance controls
the architecture differs fundamentally from the available foundation
adapting the boilerplate would take more effort than creating the system directly

A useful engineering rule is:

Build it from scratch when the infrastructure itself is part of the learning or differentiation. Reuse it when it is only a prerequisite for the real product.

Developers should understand the systems they reuse. Reuse is not a substitute for knowledge. It is a way to apply that knowledge without repeating the same implementation work indefinitely.

For a more detailed comparison, read Spring Boot Authentication Boilerplate vs. Building From Scratch.

I. Build the Product Layer, Not the Setup Layer

AI coding tools provide the most leverage when they operate inside a stable system.

The backend foundation should provide the repeated infrastructure:

authentication
authorization
validation
exception handling
storage boundaries
application structure
test patterns

The coding agent should focus on what makes the product different:

domain workflows
integrations
automation
permissions specific to the business
reporting
billing behavior
collaboration features
operational rules

The developer remains responsible for architecture, security, review, and delivery quality.

This division of responsibility creates a more scalable workflow:

The foundation supplies trusted infrastructure.
Repository documentation supplies context.
AI implements a bounded product change.
Tests verify the new behavior.
Human review protects architecture and security.

That is a better operating model than asking an AI tool to rebuild the entire backend every time.

J. Start With a Stable Spring Boot Foundation

BuildBaseKit provides Spring Boot foundations for authentication, file storage, and reusable backend architecture.

The projects are designed to help developers and coding agents begin with working infrastructure, explicit conventions, and a predictable structure.

Explore the available Spring Boot boilerplates or review the approach behind AI-ready project context.

K. Frequently Asked Questions

1. Does using a boilerplate limit product flexibility?

Not inherently. A good foundation standardizes repeated infrastructure while leaving domain models, workflows, integrations, and product services open for extension.

The risk comes from using a rigid or poorly understood foundation, not from reuse itself.

2. Why does this approach improve AI output?

The coding agent has patterns to follow. It can inspect existing controllers, services, authorization rules, DTOs, exceptions, and tests instead of inventing each convention.

3. Does a foundation automatically make generated code secure?

No.

It reduces the number of security decisions being regenerated, but every new authorization rule, data-access path, file operation, and integration still requires review and testing.

4. Is this workflow specific to Spring Boot?

The principle applies to most backend stacks. It is especially useful in Spring Boot because authentication, Spring Security, validation, persistence, and application layering involve many connected configuration and design decisions.

5. Should developers still learn how the infrastructure works?

Yes.

A foundation should be readable and modifiable. The goal is to stop repeating solved setup work, not to turn backend infrastructure into a black box.

Spring Boot Authentication Architecture: JWT and Clean Setup — organize authentication without mixing token logic and product workflows.
Spring Boot Authentication Boilerplate vs. Building From Scratch — evaluate the trade-offs between reuse, control, learning, and delivery speed.
Spring Boot File Upload: Production-Ready System Design Guide — design secure uploads, metadata, storage, and delivery.
How to Store and Serve Files in Spring Boot — build a local-storage implementation with clean boundaries.
How to Deploy a Production-Ready File Server on a VPS — cover the deployment and operational requirements around a Spring Boot file server.

Originally published by BuildBaseKit. This CoderLegion edition has been restructured and edited for the CoderLegion developer community.

Upload Files to AWS S3 with Spring Boot (Clean Architecture Guide)

Sun, 12 Apr 2026 16:42:50 +0000

Uploading files to AWS S3 in Spring Boot is simple.

Designing it properly for production is where most developers struggle.

Most implementations end up like this:

controllers handling everything
direct S3 calls everywhere
no structure
hard to scale later

In this guide, you’ll learn how to build a clean, scalable file upload system.

Building file uploads in production is harder than it looks.

If you want a clean, ready-to-use setup instead of building everything yourself:
https://buildbasekit.com/boilerplates/filora-fs-pro/

Quick Answer

The best way to upload files to S3 in Spring Boot:

separate storage logic into a service layer
avoid direct S3 calls in controllers
use pre-signed URLs for scalability

Why use AWS S3

S3 is the standard for file storage in backend systems.

handles large files and high traffic
highly scalable and durable
no infrastructure management
supports secure access control

When to use S3 vs local storage

Use S3 when:

building production systems
handling user uploads
running multiple instances

Use local storage when:

prototyping
small internal tools

Avoid local storage in distributed systems.

High-level architecture

A clean file upload system should look like this:

Controller → handles incoming requests
Service → processes file logic
Storage layer → interacts with S3
Database → stores file metadata

This separation keeps your code maintainable.

File metadata design

Do not just upload files.

Store metadata like:

file name
unique ID
S3 object key
file size and type
upload timestamp
user reference

This enables search, access control, and tracking.

Example API design

A simple API structure:

POST /files → upload file
GET /files/{id} → fetch metadata
GET /files/{id}/url → get access URL

Upload flow

client sends upload request
backend validates file
file is uploaded to S3
metadata is stored in database
response returns file reference

Keep storage logic abstract

Do not tightly couple your app with S3.

define a storage interface
implement S3 separately
allow switching providers later

This makes your system flexible.

Security considerations

Always handle security properly:

validate file type and size
avoid exposing S3 bucket directly
manage credentials securely
use pre-signed URLs

Pre-signed URLs (important)

Better approach:

backend generates upload URL
client uploads directly to S3
backend stores metadata

This:

reduces server load
improves scalability

Common mistakes

calling S3 directly from controller
hardcoding credentials
skipping metadata storage
mixing upload and access logic

Final thoughts

Uploading files to S3 is easy.

Designing a clean system is what matters long term.

If you skip structure now, it will become painful later.

Skip the setup

If you're building anything serious, don't spend days structuring this.

Use a production-ready backend instead:
https://buildbasekit.com/boilerplates/filora-fs-pro/

clean architecture
S3 + pre-signed URLs
ready APIs

Build faster. Focus on real features.

How to Deploy a Production-Ready File Server on a VPS for Free

Sun, 12 Apr 2026 16:42:31 +0000

Deploying a file server sounds simple.

Making it production-ready is where most developers struggle.

You don’t just need to run the app.
You need to:

keep it running
secure it
handle traffic properly

In this guide, you’ll deploy a real file server using Spring Boot, Nginx, and a VPS.

Start with a ready backend

Instead of building everything from scratch, you can start with a ready file server backend.

https://buildbasekit.com/boilerplates/filora-fs-lite/

It already includes:

file upload APIs
clean project structure
production-ready setup
easy deployment flow (used in this guide)

You can follow this tutorial directly using this boilerplate.

What you’ll build

By the end, you’ll have a file server that:

accepts file uploads
runs continuously with systemd
serves traffic via Nginx
uses HTTPS (SSL)
is protected with a firewall

Prerequisites

VPS (Ubuntu recommended)
Java installed
your Spring Boot jar ready
domain (optional but needed for HTTPS)

1. Prepare your app

Do not hardcode configs.

Use environment variables instead.

Example:


spring.application.name=filorafs
server.port=8080
storage.local.path=/opt/filora/uploads

2. Connect to your VPS


ssh -i your-key.key ubuntu@your-ip

Install dependencies:


sudo apt update && sudo apt upgrade -y
sudo apt install openjdk-21-jdk nginx ufw -y

3. Setup app directory


sudo mkdir -p /opt/filora
sudo chown -R $USER:$USER /opt/filora

Upload your jar:


scp target/app.jar ubuntu@your-ip:/opt/filora/

4. Add environment variables

Create .env file:


DB_PASSWORD=your_password
SERVER_PORT=8080
STORAGE_PATH=/opt/filora/uploads

5. Run app manually


cd /opt/filora
source .env
java -jar app.jar

If it works → move forward.

6. Setup systemd (important)

Create service:


sudo nano /etc/systemd/system/app.service

Paste:


[Unit]
Description=File Server
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/opt/filora
EnvironmentFile=/opt/filora/.env
ExecStart=/usr/bin/java -jar /opt/filora/app.jar
Restart=always

[Install]
WantedBy=multi-user.target

Start service:


sudo systemctl daemon-reload
sudo systemctl enable app
sudo systemctl start app

7. Setup Nginx


sudo nano /etc/nginx/sites-available/app


server {
listen 80;
server_name yourdomain.com;

client_max_body_size 100M;

location / {
    proxy_pass http://localhost:8080;
}

}

Enable:


sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

8. Add HTTPS


sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com

9. Secure server


sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Do NOT expose port 8080 publicly.

10. Test everything

upload file
check logs
verify HTTPS

Logs:


journalctl -u app -f

Common mistakes

exposing backend port directly
wrong file permissions
hardcoded configs
skipping HTTPS

Final thoughts

A file server is easy to build.

A production-ready setup is what actually matters.

Once you understand this flow:
build → deploy → proxy → secure

you can deploy almost any backend.

Skip the setup

If you don’t want to do all this manually:

https://buildbasekit.com/boilerplates/filora-fs-lite/

ready backend
file upload APIs
production structure
open source

Build faster. Focus on features.

All Spring Boot Annotations — One Cheat Sheet

Wed, 04 Mar 2026 16:40:49 +0000

See the link

Building Production-Ready Spring Boot Microservices: Lessons from Scaling to Millions

Thu, 12 Feb 2026 05:38:38 +0000

Introduction

Over the past several years working in e-commerce, I've architected and scaled microservices handling millions of customer requests daily, including platforms processing over $100M in transactions. In this article, I'll share practical patterns for building Spring Boot microservices that can handle production scale.

This isn't theory—these are battle-tested approaches proven under real-world load.

1. Service Boundaries and Domain-Driven Design

The biggest mistake teams make is creating microservices that are too granular or tightly coupled.

Key principle: Each service should own a complete business capability.

// ❌ BAD: Services that are too granular
CustomerNameService
CustomerAddressService

// ✅ GOOD: Services that own complete domains
CustomerProfileService // owns all customer identity/profile data
SubscriptionService    // owns subscriptions, benefits, rewards

When building a subscription platform, a SubscriptionService should own the complete domain: enrollment, benefits tracking, payment integration, and conversions. This prevents the "distributed monolith" where you call 10 services for one operation.

2. Handling Distributed Transactions with Saga Pattern

At scale, distributed transactions become your enemy. Here's the orchestration approach:

@Service
public class SubscriptionEnrollmentOrchestrator {
    
    @Transactional
    public EnrollmentResult enrollMember(EnrollmentRequest request) {
        // Step 1: Validate customer (synchronous)
        CustomerProfile customer = customerClient.getCustomer(request.getCustomerId())
            .orElseThrow(() -> new CustomerNotFoundException());
            
        // Step 2: Process payment (synchronous with compensation)
        PaymentResult payment;
        try {
            payment = paymentClient.processPayment(request.getPaymentMethod());
        } catch (PaymentException e) {
            throw new EnrollmentFailedException("Payment failed", e);
        }
        
        // Step 3: Create subscription (local transaction)
        Subscription subscription;
        try {
            subscription = createSubscription(customer, payment);
            subscriptionRepository.save(subscription);
        } catch (Exception e) {
            // Compensate payment
            paymentClient.refundPayment(payment.getTransactionId());
            throw new EnrollmentFailedException("Subscription creation failed", e);
        }
        
        // Step 4: Publish event for async operations
        eventPublisher.publish(new SubscriptionEnrolledEvent(subscription));
        
        return EnrollmentResult.success(subscription);
    }
}

Key lessons:

Make operations idempotent - Include transaction IDs so retries don't cause duplicates
Compensate explicitly - If step N fails, undo steps 1 through N-1
Separate critical path from eventual consistency - Payment is synchronous, emails are async

3. Strategic Caching for High-Traffic Systems

We reduced database load by 85% through strategic caching:

@Service
public class SubscriptionService {
    
    private final LoadingCache<String, Optional<Subscription>> cache;
    
    public SubscriptionService(SubscriptionRepository repository) {
        this.cache = CacheBuilder.newBuilder()
            .maximumSize(10_000)
            .expireAfterWrite(5, TimeUnit.MINUTES)
            .recordStats()
            .build(CacheLoader.from(repository::findByCustomerId));
    }
    
    @Transactional
    public Subscription updateSubscription(String id, SubscriptionUpdate update) {
        Subscription updated = repository.findById(id)
            .map(s -> applyUpdate(s, update))
            .orElseThrow(() -> new SubscriptionNotFoundException(id));
            
        repository.save(updated);
        cache.invalidate(updated.getCustomerId()); // Invalidate on write
        
        return updated;
    }
}

Caching layers:

Application-level (Guava/Caffeine) - 5-minute TTL for hot data
Redis distributed cache - 15-minute TTL for cross-instance consistency
Database with proper indexing

4. Circuit Breakers and Resilience

When calling other services, assume they will fail:

@Service
public class CustomerProfileClient {
    
    @CircuitBreaker(name = "customer-profile", fallbackMethod = "getCustomerFallback")
    @TimeLimiter(name = "customer-profile")
    public CompletableFuture<CustomerProfile> getCustomer(String customerId) {
        return CompletableFuture.supplyAsync(() -> 
            restTemplate.getForObject("/api/customers/" + customerId, CustomerProfile.class)
        );
    }
    
    private CompletableFuture<CustomerProfile> getCustomerFallback(String customerId, Exception ex) {
        log.warn("Customer service unavailable, using cached data");
        return CompletableFuture.completedFuture(
            customerCache.get(customerId)
                .orElseThrow(() -> new ServiceUnavailableException("No cached data", ex))
        );
    }
}

Configuration:

CircuitBreakerConfig.custom()
    .failureRateThreshold(50)          // Open if 50% fail
    .waitDurationInOpenState(Duration.ofSeconds(30))
    .slidingWindowSize(100)            // Consider last 100 calls
    .slowCallDurationThreshold(Duration.ofSeconds(2))
    .build();

5. Structured Logging and Distributed Tracing

You can't fix what you can't see:

@Slf4j
@RestController
public class SubscriptionController {
    
    @PostMapping("/subscriptions")
    public ResponseEntity<SubscriptionResponse> enrollMember(
            @RequestBody EnrollmentRequest request,
            @RequestHeader("X-Request-ID") String requestId) {
        
        MDC.put("requestId", requestId);
        MDC.put("customerId", request.getCustomerId());
        
        try {
            log.info("Starting enrollment", 
                kv("tier", request.getTier()),
                kv("paymentMethod", request.getPaymentMethod().getType()));
            
            Instant start = Instant.now();
            EnrollmentResult result = enrollmentService.enroll(request);
            
            log.info("Enrollment completed",
                kv("subscriptionId", result.getSubscriptionId()),
                kv("durationMs", Duration.between(start, Instant.now()).toMillis()));
            
            return ResponseEntity.ok(toResponse(result));
        } finally {
            MDC.clear();
        }
    }
}

Logging standards:

Use structured key-value pairs, not string concatenation
Track request IDs across service boundaries
Include customer ID and operation type in every log

6. Database Query Optimization

Slow queries kill scalability:

@Entity
@Table(name = "subscriptions", indexes = {
    @Index(name = "idx_customer_id", columnList = "customer_id"),
    @Index(name = "idx_tier_status", columnList = "tier, status"),
    @Index(name = "idx_expires_at", columnList = "expires_at")
})
public class Subscription {
    // Use @BatchSize to prevent N+1 queries
    @OneToMany(mappedBy = "subscription", fetch = FetchType.LAZY)
    @BatchSize(size = 50)
    private List<Benefit> benefits;
}

@Repository
public interface SubscriptionRepository extends JpaRepository<Subscription, String> {
    
    // Custom query with fetch join to avoid N+1
    @Query("SELECT s FROM Subscription s LEFT JOIN FETCH s.benefits WHERE s.customerId = :customerId")
    Optional<Subscription> findByCustomerIdWithBenefits(@Param("customerId") String customerId);
}

Performance lessons:

Index everything you query by
Use batch fetching to prevent N+1 queries
Paginate large results
Monitor and alert on queries >100ms

7. Connection Pool Tuning

spring:
  datasource:
    hikari:
      # Formula: (core_count * 2) + effective_spindle_count
      # For 4-core with SSD: (4 * 2) + 1 = 9
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 3000
      validation-timeout: 1000
      leak-detection-threshold: 60000
      max-lifetime: 1800000  # 30 minutes

8. Zero-Downtime Deployments

# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: subscription-service
spec:
  replicas: 6
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 3        # Add 50% extra during update
      maxUnavailable: 1  # Keep 5/6 running
  template:
    spec:
      containers:
      - name: subscription-service
        readinessProbe:
          httpGet:
            path: /actuator/health/readiness
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /actuator/health/liveness
            port: 8080
          initialDelaySeconds: 60
          periodSeconds: 10

9. Metrics That Matter

@Service
public class MetricsService {
    
    private final Counter enrollmentsCounter;
    private final Timer enrollmentDuration;
    
    public MetricsService(MeterRegistry registry) {
        this.enrollmentsCounter = Counter.builder("subscription.enrollments")
            .tag("service", "subscription")
            .register(registry);
            
        this.enrollmentDuration = Timer.builder("subscription.enrollment.duration")
            .publishPercentiles(0.5, 0.95, 0.99)
            .register(registry);
    }
}

Monitor:

Business: Enrollments/hour, conversion rate, revenue
Technical: P50/P95/P99 latency, error rate, throughput
Infrastructure: CPU, memory, connection pool utilization

10. Testing Strategy

// Unit tests - fast, isolated
@Test
void shouldCalculateCorrectExpirationDate() {
    EnrollmentService service = new EnrollmentService(
        mock(CustomerClient.class),
        mock(PaymentClient.class),
        mock(SubscriptionRepository.class)
    );
    
    Instant enrolledAt = Instant.parse("2024-01-01T00:00:00Z");
    Instant expected = Instant.parse("2025-01-01T00:00:00Z");
    
    assertEquals(expected, service.calculateExpiration(enrolledAt, SubscriptionTier.ANNUAL));
}

// Integration tests - with real database
@SpringBootTest
@Testcontainers
class SubscriptionServiceIntegrationTest {
    
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");
    
    @Test
    void shouldPersistAndRetrieveSubscription() {
        EnrollmentResult result = service.enroll(request);
        Optional<Subscription> retrieved = service.getSubscription(result.getSubscriptionId());
        
        assertTrue(retrieved.isPresent());
        assertEquals(SubscriptionTier.BASIC, retrieved.get().getTier());
    }
}

Key Takeaways

After building and scaling microservices handling millions of requests:

Design for failure - Circuit breakers, timeouts, and fallbacks are not optional
Embrace eventual consistency - Not everything needs to be synchronous
Observability is critical - You can't improve what you can't measure
Cache aggressively - But invalidate intelligently
Test at every level - Unit, integration, contract, and load tests
Automate deployments - Including rollbacks and scaling
Performance is a feature - Optimize from day one

What's Next?

In future posts, I'll dive deeper into:

Advanced observability with distributed tracing
Chaos engineering and resilience testing
Cost optimization for cloud deployments

Questions or want to discuss these patterns? Leave a comment below or connect with me on LinkedIn.

Tags: #spring-boot #microservices #java #system-design #aws #architecture #scalability #production-engineering

Client side pagination is not good in some cases

Fri, 08 Aug 2025 20:29:08 +0000

The Pagination Pitfall: A React + Spring Boot Cautionary Tale

The Setup: "It’ll Be Fine..."

A few years ago, I was working on a dashboard application with a React frontend and a Spring Boot backend. The task seemed simple: display a list of users with pagination.

One of the newer devs suggested:

“Let’s just fetch everything once and paginate on the client side — it’ll be faster for the user.”

We had maybe 500 users at the time, so… sure. Why not?

And then we shipped it.

The Plot Twist: Growth Happens

A few months passed.

Marketing launched a campaign that worked too well.
Suddenly, instead of 500 users, we had 250,000+.

The dashboard became unusable. The browser would freeze, mobile devices would crash, and CPU usage would spike through the roof.
Our once-smooth user experience turned into a memory-leaking nightmare.

⚠️ The Mistake: Client-Side Pagination at Scale

Client-side pagination works only when:

The dataset is small and controlled
The entire dataset can be loaded efficiently in the browser
You don’t expect explosive growth

But when you're working with Spring Boot APIs and React, it's tempting to fetch all data via a single REST call, dump it into state, and let React handle the UI slicing.

What’s wrong with that?

You're sending huge payloads over the wire
You're increasing memory usage on the frontend
You’re locking users into long initial load times
You make updates or filtering much harder

✅ The Fix: Server-Side Pagination with Spring Boot + React

We refactored. Here’s what we did:

Backend (Spring Boot)

We used Pageable from Spring Data:

@GetMapping("/users")
public Page<User> getUsers(Pageable pageable) {
    return userRepository.findAll(pageable);
}

Spring Boot handles page number, size, sorting, and total count under the hood.

Frontend (React)

We called the API with query parameters like ?page=0&size=20:

const fetchUsers = async (page, size) => {
  const res = await fetch(`/api/users?page=${page}&size=${size}`);
  const data = await res.json();
  setUsers(data.content);
  setTotalPages(data.totalPages);
};

We then plugged this into a pagination UI. Now, we load only what we need, keep response times fast, and keep the browser happy.

Lessons Learned

React + Spring Boot is a powerful combo — but scale with caution
Don’t optimize for “today’s data” unless you’re certain it won’t grow
Use Spring’s Pageable and let the database do the heavy lifting
Keep network traffic and frontend memory usage lean
Premature optimization is bad, but premature de-optimization is worse

TL;DR

Using client-side pagination for large or unknown datasets is like bringing a spoon to a firefight.

It might work — for a while — but you’re setting yourself up for disaster.

Use the right tools. Paginate smart. Scale with confidence.

Coder Legion - Recent posts tagged spring-boot

The Legacy Report Was Going Away. The Agent Still Needed the Answer.

First, migrate the decision—not the screen

Put a stable API between Salesforce and reporting data

Access control must follow the data all the way through

Prove the new path under production-like conditions

What this kind of migration teaches

References

Spring Boot Authentication Boilerplate: From JWT Basics to Production-Ready Auth

The auth code isn't the interesting part

AuthKit Lite

When Lite isn't enough

Lite or Pro?

Why a boilerplate?

AI Can Write Your Backend—But It Shouldn’t Rebuild the Foundation Every Time

A. The Wrong Way to Measure AI Development Speed

B. Why Rebuilding Backend Infrastructure With AI Creates Drift

1. Separate prompts create separate architectural decisions

2. Every correction expands the prompt

3. Security code has a high verification cost

C. What the Backend Foundation Should Already Provide

1. Authentication and token lifecycle

2. Authorization

3. Validation and exception handling

4. File handling and storage boundaries

5. Clear application layers

6. A usable testing strategy

D. A Better AI-Assisted Backend Workflow

1. Begin with a known backend foundation

2. Verify the baseline before extending it

3. Put architectural context inside the repository

4. Request one bounded product change

5. Review the patch as a change, not as a new system

6. Test the business behavior

E. Why This Workflow Uses Fewer Tokens

F. Why Existing Context Improves Generated Code

G. Common Failure Modes

1. Regenerating authentication for each application

2. Adding uploads without defining access rules

3. Mixing business rules with Spring Security

4. Trusting plausible generated security code

5. Sending one massive implementation prompt

6. Measuring generated lines instead of delivered value

H. When Building From Scratch Is Still the Right Choice

I. Build the Product Layer, Not the Setup Layer

J. Start With a Stable Spring Boot Foundation

K. Frequently Asked Questions

1. Does using a boilerplate limit product flexibility?

2. Why does this approach improve AI output?

3. Does a foundation automatically make generated code secure?

4. Is this workflow specific to Spring Boot?

5. Should developers still learn how the infrastructure works?

L. Related BuildBaseKit Articles

Upload Files to AWS S3 with Spring Boot (Clean Architecture Guide)

Quick Answer

Why use AWS S3

When to use S3 vs local storage

High-level architecture

File metadata design

Example API design

Upload flow

Keep storage logic abstract

Security considerations

Pre-signed URLs (important)

Common mistakes

Final thoughts

Skip the setup

How to Deploy a Production-Ready File Server on a VPS for Free

Start with a ready backend

What you’ll build

Prerequisites

1. Prepare your app

2. Connect to your VPS

3. Setup app directory

4. Add environment variables

5. Run app manually

6. Setup systemd (important)

7. Setup Nginx

8. Add HTTPS

9. Secure server