WIP MITInstructors

Spring Boot From Scratch

Build a production-ready API with Spring Boot 3 from scratch

Status
WIP
License
MIT
Category
Instructors
Updated

Project status

Description

Spring Boot From Scratch is a 6-week learning path aimed at junior-to-mid developers who want to learn Spring Boot 3 from the ground up. It is not another copy-paste tutorial: each module introduces a concept (REST controllers, validation, JPA persistence, JWT security, testing with Testcontainers, observability with Actuator) and applies it to a real domain - a shared task management system. The code is organized in progressive branches (`step-01-rest-skeleton`, `step-02-validation`, `step-03-jpa`, up to `step-12-native-image`), so you can compare your work with the reference solution at every checkpoint. The philosophy is build-your-own: students write code, they do not watch it passively. Each step includes optional exercises to explore alternatives (Hibernate vs JdbcTemplate, JWT vs Session, MapStruct vs manual mapping, Maven vs Gradle). Tests are first-class: every feature has unit tests (JUnit 5 + Mockito) and integration tests (Testcontainers + real PostgreSQL, not in-memory H2). The MkDocs Material documentation includes C4 diagrams (levels 1-2-3), ADRs (Architecture Decision Records) for every architectural choice and a troubleshooting section with the common problems developers meet on their first approach. The project is MIT-licensed, permissive, meant to be cloned, modified and used as a scaffold for real production projects. Aligned with the brand 'Backend Developer & ML Engineer for startups and IT/EU SMEs': the code reflects concrete enterprise patterns (Clean Architecture, constructor dependency injection, records for DTOs, immutability-first, validation at system boundaries) but remains accessible to those starting completely from zero, without assuming prior knowledge of Java EE or legacy Spring.

Key Features

  • Progressive path by step

    12-step branch-based: Each Git branch is a checkpoint with code, tests, and ADR. Easy comparison between your work and reference solution.

  • JPA and Hibernate Hands-On Experience

    Entity, repository, query JPQL, native query, fetch strategy, N+1 problem detection with Hibernate statistics and p6spy.

  • Proprietary JWT Security

    Implementation of lightweight JWT HS256 without heavy external dependencies (optional jjwt), refresh token rotation, password reset flow, rate limiting with Bucket4j.

  • Testing First-Class

    Unit test (JUnit 5 + Mockito), integration test (Testcontainers + PostgreSQL real), MockMvc for controller tests. Coverage 80%+ enforced via JaCoCo.

  • Built-in observability

    Spring Boot Actuator + Micrometer + Prometheus, structured JSON logs with Logback + MDC, custom health checks.

  • Living documentation

    MkDocs Material with C4 diagrams (Structurizr), an ADR for every architectural decision, OpenAPI 3.1 auto-generated with springdoc.

  • Production-ready hardening

    GraalVM native image optional, optimized multi-stage Dockerfile, profiles for dev/staging/prod, externalize secrets via environment variables.

Tech stack

  • Spring Boot 3.4
  • Java 21
  • Maven
  • Spring Data JPA
  • Hibernate 6
  • PostgreSQL 16
  • Testcontainers
  • JUnit 5
  • Mockito
  • MkDocs Material

Use cases

  • Junior developers who want to learn Spring Boot 3 with a structured path and progressive branches.
  • Bootcamps and university courses seeking up-to-date open-source educational material for Java 21 + Spring Boot 3.
  • Developers who want to refresh modern patterns (records, virtual threads, GraalVM native) in a real-world context.
  • Team looking for a clean scaffold for new enterprise Spring Boot projects

Road Map

  1. v0.1.0Scheduled

    Foundation: REST + Validation + JPA

    • Step 1: Controller with REST Skeleton and DTO Records
    • Step 2: Bean Validation with Custom Validator
    • Step 3: JPA Repository, Entity, and Flyway Migration
    • Step 4: Service Layer with Transactional Boundary
    • Setup MkDocs + ADR-0001 (Clean Architecture)
  2. v0.5.0Scheduled

    Security, Testing and Observability

    • Step 5-6: JWT auth + refresh rotation
    • Step 7: Container Integration Test with Testcontainers
    • Step 8: Spring Boot Actuator + Prometheus
    • Step 9: Rate Limiting with Bucket4j
    • Target coverage of at least 80%.
  3. v1.0.0Scheduled

    Production Hardening + Native Image

    • Step 10: Multi-Stage Dockerfile with Docker Compose
    • Step 11: GraalVM Native Image Build
    • Step 12: Performance Benchmark and JVM Tuning
    • Complete MkDocs documentation and VPS deployment guide
    • Release v1.0.0 + Announce Community

Who is it for

  • Tech enthusiasts
  • For Developer - Junior/Mid-Level

Quick start

Start the project locally in just a few commands. 

# Quick start (work-in-progress, repo non ancora pubblicato)
# git clone https://github.com/<tba>/spring-boot-from-scratch.git
# cd spring-boot-from-scratch
# git checkout step-01-rest-skeleton
# ./mvnw spring-boot:run
# curl http://localhost:8080/api/v1/tasks