Explain your Spring Boot project architecture.

What Spring Boot project architecture really means

Think of architecture as the path a request follows from the outside world to your database and back. Good architecture keeps each step small and predictable, so one bug does not spread everywhere. In Spring Boot, that usually means a controller layer, a service layer, a repository layer, plus DTOs, config, security, and exception handling.

My usual package layout

order/controller for REST endpoints
order/service for business rules
order/repository for persistence
order/dto for request and response models
order/entity for database objects
common/exception and common/config for shared concerns

This is often called a feature-first layout: inside each feature, you still keep layers, but the code stays grouped by business area. That helps when a system grows from 5 endpoints to 50.

How it works under the hood

Spring Boot starts from the main class and creates the ApplicationContext, which is the container that owns your beans. It scans the package tree below the main class, so your package placement matters.
The embedded server accepts traffic. In a web app, Boot usually runs Tomcat by default. Tomcat commonly has a max worker thread count of about 200, so if you block threads with slow work, requests queue up fast.
DispatcherServlet routes the request to the matching controller method. This is the central front controller in Spring MVC.
The controller translates HTTP into Java. It reads path variables, query params, and JSON bodies, then maps them into DTOs. DTO stands for Data Transfer Object, a simple object used only to carry data across boundaries.
The service executes the use case. This is where validation, orchestration, and transaction boundaries belong. If a request needs multiple repository calls or an external API call, the service owns that flow.
The repository handles persistence. With JPA, it talks to the database through Hibernate; with JDBC, it uses SQL directly. Repository code should be thin and predictable.
The response goes back out as a response DTO, and any exception is turned into a clean HTTP status by a global handler such as @RestControllerAdvice.

Why I prefer this structure

Testability: you can unit test services without starting the whole web layer.
Maintainability: changing database tables does not force API changes if DTOs are separate.
Team work: one person can change validation, another can change persistence, with fewer merge conflicts.
Safer refactoring: the boundaries make it obvious where rules belong.

Layered vs hexagonal

Most Spring Boot apps start with layered architecture because it is simple and familiar. For very complex systems, teams sometimes move toward hexagonal architecture, also called ports and adapters, where the business core is isolated from frameworks.

Style	Best for	Trade-off
Layered	CRUD and service apps	Can get coupled if controllers call repositories directly
Hexagonal	Complex domain logic	More files and more abstraction

Rule of thumb: start layered, keep feature grouping, and evolve only when complexity demands it.

Performance and edge cases

Bean scanning: startup time grows with the number of beans and classes. A small Boot API often starts in roughly 1 to 3 seconds locally; large apps with heavy JPA scanning can take longer.
Database pool: HikariCP, the default connection pool in Boot, commonly uses a max pool size of 10 if you do not tune it. Its default connection timeout is 30000 ms.
Complexity: controller-service-repository routing is logically O(1) per request; the real cost is usually I/O, not Java method calls.
Version note: Spring Boot 3 uses jakarta.* packages, while older Boot 2 code often used javax.*. This is a common interview gotcha when reading older tutorials.
Edge case: if your main class is not in a root package, component scanning can miss controllers or services, and your app may start but endpoints return 404.

So, when I explain architecture, I focus on flow, separation of concerns, and where the business rules live. That tells the interviewer I understand not just the folder structure, but why the structure keeps the app safe as it grows.

// File: src/main/java/com/example/architecture/ArchitectureDemoApplication.java package com.example.architecture; import org.springframework.boot.CommandLineRunner; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; @SpringBootApplication public class ArchitectureDemoApplication { public static void main(String[] args) { SpringApplication.run(ArchitectureDemoApplication.class, args); } @Bean CommandLineRunner seedDemoData(OrderService orderService) { // Seed data helps show that the service layer can be called from anywhere, // not just from HTTP. In a real app, the same service would be reused by tests, // schedulers, or message listeners. return args -> orderService.createOrder(new CreateOrderRequest("Keyboard", 1, 49.99)); } } // File: src/main/java/com/example/architecture/ApiModels.java package com.example.architecture; // These are DTOs: small objects that cross the HTTP boundary without exposing persistence details. record CreateOrderRequest(String item, int quantity, double unitPrice) {} record OrderResponse(Long id, String item, int quantity, double unitPrice, double total) {} // Package-private exception is enough because it is only used inside this package. class NotFoundException extends RuntimeException { NotFoundException(String message) { super(message); } } // File: src/main/java/com/example/architecture/OrderEntity.java package com.example.architecture; // This is a persistence model. In a real JPA app, this might be an @Entity. class OrderEntity { private Long id; private String item; private int quantity; private double unitPrice; OrderEntity(Long id, String item, int quantity, double unitPrice) { this.id = id; this.item = item; this.quantity = quantity; this.unitPrice = unitPrice; } OrderEntity copy() { return new OrderEntity(id, item, quantity, unitPrice); } Long getId() { return id; } void setId(Long id) { this.id = id; } String getItem() { return item; } int getQuantity() { return quantity; } double getUnitPrice() { return unitPrice; } } // File: src/main/java/com/example/architecture/OrderRepository.java package com.example.architecture; import java.util.List; import java.util.Optional; // Repository is the data-access boundary. The service should not know whether this is a DB, a map, or a remote store. public interface OrderRepository { OrderEntity save(OrderEntity entity); Optional<OrderEntity> findById(Long id); List<OrderEntity> findAll(); } // File: src/main/java/com/example/architecture/InMemoryOrderRepository.java package com.example.architecture; import java.util.Comparator; import java.util.List; import java.util.Optional; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; import java.util.concurrent.atomic.AtomicLong; import org.springframework.stereotype.Repository; @Repository class InMemoryOrderRepository implements OrderRepository { private final ConcurrentMap<Long, OrderEntity> store = new ConcurrentHashMap<>(); private final AtomicLong sequence = new AtomicLong(0); @Override public OrderEntity save(OrderEntity entity) { // Assign an ID only when needed. This mimics a database-generated key. Long id = entity.getId(); if (id == null) { id = sequence.incrementAndGet(); } OrderEntity saved = new OrderEntity(id, entity.getItem(), entity.getQuantity(), entity.getUnitPrice()); store.put(id, saved); return saved.copy(); } @Override public Optional<OrderEntity> findById(Long id) { OrderEntity entity = store.get(id); return entity == null ? Optional.empty() : Optional.of(entity.copy()); } @Override public List<OrderEntity> findAll() { return store.values().stream() .map(OrderEntity::copy) .sorted(Comparator.comparing(OrderEntity::getId)) .toList(); } } // File: src/main/java/com/example/architecture/OrderService.java package com.example.architecture; import java.util.List; import org.springframework.stereotype.Service; @Service public class OrderService { private final OrderRepository orderRepository; public OrderService(OrderRepository orderRepository) { // Constructor injection makes dependencies obvious and avoids nulls. this.orderRepository = orderRepository; } public OrderResponse createOrder(CreateOrderRequest request) { validate(request); OrderEntity saved = orderRepository.save( new OrderEntity(null, request.item(), request.quantity(), request.unitPrice()) ); return toResponse(saved); } public OrderResponse getOrder(Long id) { OrderEntity entity = orderRepository.findById(id) .orElseThrow(() -> new NotFoundException("Order " + id + " not found")); return toResponse(entity); } public List<OrderResponse> listOrders() { return orderRepository.findAll().stream() .map(this::toResponse) .toList(); } private void validate(CreateOrderRequest request) { if (request == null) { throw new IllegalArgumentException("Request body is required"); } if (request.item() == null || request.item().isBlank()) { throw new IllegalArgumentException("Item is required"); } if (request.quantity() <= 0) { throw new IllegalArgumentException("Quantity must be greater than zero"); } if (request.unitPrice() <= 0.0) { throw new IllegalArgumentException("Unit price must be greater than zero"); } } private OrderResponse toResponse(OrderEntity entity) { double total = entity.getQuantity() * entity.getUnitPrice(); return new OrderResponse(entity.getId(), entity.getItem(), entity.getQuantity(), entity.getUnitPrice(), total); } } // File: src/main/java/com/example/architecture/OrderController.java package com.example.architecture; import java.util.List; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/orders") public class OrderController { private final OrderService orderService; public OrderController(OrderService orderService) { this.orderService = orderService; } @PostMapping public ResponseEntity<OrderResponse> create(@RequestBody CreateOrderRequest request) { // The controller stays thin: it only translates HTTP to a service call. OrderResponse response = orderService.createOrder(request); return ResponseEntity.status(HttpStatus.CREATED).body(response); } @GetMapping("/{id}") public OrderResponse getById(@PathVariable Long id) { return orderService.getOrder(id); } @GetMapping public List<OrderResponse> list() { return orderService.listOrders(); } } // File: src/main/java/com/example/architecture/ApiExceptionHandler.java package com.example.architecture; import java.util.LinkedHashMap; import java.util.Map; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; @RestControllerAdvice public class ApiExceptionHandler { @ExceptionHandler(NotFoundException.class) public ResponseEntity<Map<String, Object>> handleNotFound(NotFoundException ex) { return build(HttpStatus.NOT_FOUND, "NOT_FOUND", ex.getMessage()); } @ExceptionHandler(IllegalArgumentException.class) public ResponseEntity<Map<String, Object>> handleBadRequest(IllegalArgumentException ex) { return build(HttpStatus.BAD_REQUEST, "BAD_REQUEST", ex.getMessage()); } @ExceptionHandler(Exception.class) public ResponseEntity<Map<String, Object>> handleUnexpected(Exception ex) { // A last-resort handler keeps clients from seeing a raw stack trace. return build(HttpStatus.INTERNAL_SERVER_ERROR, "INTERNAL_ERROR", "Something went wrong"); } private ResponseEntity<Map<String, Object>> build(HttpStatus status, String error, String message) { Map<String, Object> body = new LinkedHashMap<>(); body.put("error", error); body.put("message", message); body.put("status", status.value()); return ResponseEntity.status(status).body(body); } } /* How to try it: 1) Start the app. 2) POST /orders with: {"item":"Mouse","quantity":2,"unitPrice":25.0} 3) GET /orders/1 to fetch the seeded record. 4) GET /orders/999 to see the 404 path. 5) POST /orders with {"item":"","quantity":0,"unitPrice":-1} to see validation handled as a clean 400. */

Follow-up & Tricky Questions:

How do you structure packages: by layer or by feature? I usually prefer feature-first for larger systems because it keeps related code together, but inside each feature I still keep controller, service, repository, DTO, and config boundaries.
Why keep DTOs separate from entities? DTOs protect your API from database changes and let you return only the fields the client needs. Entities often contain persistence details that should not leak over the wire.
Where should @Transactional live? Usually on the service layer, because that is where the business use case is orchestrated. Putting it in the controller mixes HTTP concerns with transaction control.
How do you handle exceptions cleanly? With @RestControllerAdvice and focused handlers for validation, not found, and unexpected errors. That gives clients consistent status codes and messages.
How do you test this architecture? I unit test services with mocked repositories, use web slice tests for controllers, and keep a few integration tests to verify the full path.
Can the controller call the repository directly? In a tiny demo app, yes, but in real projects it quickly creates tangled validation, transaction, and error-handling logic. The service layer is what keeps that complexity under control.
Should the main class always be in the root package? Yes, or you must explicitly set scan packages. If not, Spring may miss beans and your app starts but endpoints are not found.
Do I need a service layer for pure CRUD? Not always on day one, but once you add validation, audit, retries, or multiple data calls, the service layer becomes the right home for that logic.
Tricky: If everything compiles, can architecture still be wrong? Absolutely. A compiles-clean app can still be badly designed if controllers contain business rules, repositories are exposed to the API, or exceptions are handled inconsistently.
Tricky: Is a single package per layer enough? Only for small apps. When the codebase grows, grouping by feature usually makes navigation and ownership much easier.