DEV Community

jayanti-neu
jayanti-neu

Posted on

Building a Real-Time Freight Tracker in Java — Beginner’s Perspective

#java #springboot #backend #beginners

🚚 Building a Real-Time Freight Tracker in Java (Phase 1)

As a recent graduate stepping into backend development with Java Spring Boot, I wanted to build something real-world and practical. I've always been curious about how delivery tracking systems work so I started working on a Real-Time Freight Tracking Application.

This blog is a beginner-friendly, exploratory recap of how I built Phase 1: the core CRUD API backend.

🌟 Project Goal

Build a backend system that allows tracking of freight shipments across different locations with key details like origin, destination, status, and timestamps and more

🔧 Tech Stack Used

  • Java 17
  • Spring Boot 3.5
  • Maven
  • PostgreSQL (local DB)
  • IntelliJ IDEA (Community Edition)
  • Postman (for testing)

🧠 How the Code Works — MVC and Data Flow

🧹 Model Layer: The Domain

The core data structure is Shipment — a JPA entity mapped to a database table. Here's what it looks like:

@Entity
public class Shipment {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String origin;

    private String destination;

    @Enumerated(EnumType.STRING)
    private ShipmentStatus status;

    private LocalDateTime lastUpdatedTime;

    @Column(nullable = false, unique = true)
    private String trackingNumber;

    private String carrier;

    @Enumerated(EnumType.STRING)
    private Priority priority;

}
Enter fullscreen mode Exit fullscreen mode

What I learned here:

  • @Entity marks it as a database-mapped object
  • @Id and @GeneratedValue handle primary key logic
  • @Enumerated(EnumType.STRING) saves enums as readable strings

The ShipmentStatus enum represents fixed states:

public enum ShipmentStatus {
    PENDING, IN_TRANSIT, DELIVERED, CANCELLED
}
Enter fullscreen mode Exit fullscreen mode

And Priority (another enum) tracks urgency levels.

Lombok annotations like @Getter, @Setter, @Builder, etc. reduce boilerplate code.

🗂️ Repository Layer: Data Access

This layer connects our code with the database:

@Repository
public interface ShipmentRepository extends JpaRepository<Shipment, Long> {
    Page<Shipment> findByStatus(ShipmentStatus status, Pageable pageable);
    Page<Shipment> findByOriginIgnoreCase(String origin, Pageable pageable);
    Page<Shipment> findByOriginIgnoreCaseAndStatus(String origin, ShipmentStatus status, Pageable pageable);
    Page<Shipment> findAll(Pageable pageable);
    long countByStatus(ShipmentStatus status);

    @Query("SELECT s.origin FROM Shipment s GROUP BY s.origin ORDER BY COUNT(s) DESC LIMIT 1")
    String findMostCommonOrigin();
}
Enter fullscreen mode Exit fullscreen mode

Key Concepts:

  • Spring Data JPA uses method names to auto-generate SQL
  • Pagination is supported using Pageable — allowing APIs like: GET /api/shipments?page=0&size=10 or GET /api/shipments/search?origin=NY&status=IN_TRANSIT&page=1&size=5
  • The custom @Query uses JPQL to find the most common origin efficiently

This structure ensures scalability and efficiency.

🌐 Controller Layer: API Endpoints

Here's a simplified controller class:

@RestController
@RequestMapping("/api/shipments")
public class ShipmentController {

    @Autowired
    private ShipmentRepository shipmentRepository;

    @PostMapping
    public Shipment createShipment(@RequestBody Shipment shipment) {
        shipment.setLastUpdatedTime(LocalDateTime.now());
        return shipmentRepository.save(shipment);
    }

    @GetMapping
    public List<Shipment> getAllShipments() {
        return shipmentRepository.findAll();
    }

    @GetMapping("/search")
    public List<Shipment> searchShipments(
        @RequestParam(required = false) String origin,
        @RequestParam(required = false) ShipmentStatus status,
        Pageable pageable
    ) {
        if (origin != null && status != null) {
            return shipmentRepository.findByOriginIgnoreCaseAndStatus(origin, status, pageable);
        } else if (origin != null) {
            return shipmentRepository.findByOriginIgnoreCase(origin, pageable);
        } else if (status != null) {
            return shipmentRepository.findByStatus(status, pageable);
        } else {
            return shipmentRepository.findAll(pageable);
        }
    }
    // more endpoints...
}
Enter fullscreen mode Exit fullscreen mode

Controller Annotations Explained:

  • @RestController: Shortcut for @Controller + @ResponseBody, It automatically converts your return values (like Java objects) into JSON responses
  • @RequestMapping: Base route for the class
  • @Autowired: Dependency injection of the repository
  • @PostMapping, @GetMapping: Maps HTTP methods to Java methods
  • @RequestParam: Handles query strings like ?origin=NY
  • @RequestBody: Converts incoming JSON into Java objects

This is where HTTP meets business logic.

📊 Stats & DTOs

To keep response structure clean and decoupled from the database model, I used a DTO:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ShipmentStatsDTO {
    private long totalShipments;
    private Map<ShipmentStatus, Long> statusCounts;
    private String mostCommonOrigin;
}
Enter fullscreen mode Exit fullscreen mode

Why DTOs?

  • Keeps internal model logic separate from external API responses — this is essential for security and flexibility
  • Prevents overexposing database fields, such as sensitive IDs or internal flags
  • Makes testing and documentation easier, since DTOs define exactly what data is expected or returned
  • Helps decouple frontend and backend development — frontend teams can rely on stable response shapes even if internals change
  • Promotes consistency in API design by enforcing contract-based responses
  • Improves serialization performance and clarity by shaping only the needed data (e.g., filtering fields, renaming keys)
  • Makes integration with tools like Swagger/OpenAPI or frontend types (like TypeScript interfaces) cleaner and easier to auto-generate
  • Aids in unit testing: you can test service logic using DTOs directly without loading full entities
  • Especially useful for read-heavy APIs or summary/analytics endpoints where the result doesn't mirror a database table model logic separate from API responses
  • Prevents overexposing database fields
  • Simplifies and formats responses (like maps and summaries)

The /api/shipments/stats endpoint returns this structure.

🔧 Configuration & Secrets Management

To avoid committing passwords:

  • Gitignored application.properties
  • Used application.properties.example for public template

🧳 Directory Structure Summary 

freight-tracker/
├── model/                # Java classes like Shipment, ShipmentStatus, Priority
├── repository/           # Interfaces for DB queries (Spring Data JPA)
├── controller/           # RESTful HTTP endpoints
├── dto/                  # DTOs for stats and summaries
├── FreightTrackerApplication.java  # Main entry point
├── application.properties.local
Enter fullscreen mode Exit fullscreen mode

🧠 What I Learned in Phase 1

  • How MVC architecture connects models, repos, and controllers
  • How to build clean REST APIs using Spring Boot annotations
  • How enums and timestamps are stored using JPA
  • Query filtering using @RequestParam
  • Creating DTOs to shape and return custom responses
  • Adding pagination to repository methods for real-world scalability
  • Structuring code professionally (modularity, separation of concerns)
  • Secrets management using .gitignore
  • Endpoints tested with Postman

🗓️ What’s Coming Next

  • Real-time updates with WebSockets
  • Service layer refactor
  • UI or dashboard (React or Thymeleaf)
  • AWS RDS and cloud deployment

👩‍💻 Final Thoughts

You can check out the code on GitHub [https://github.com/jayanti-neu/freight-tracker], and stay tuned for more updates!

If you have questions or feedback, feel free to connect with me. 🚀

Top comments (0)