Spring Boot: Setup, Auto-Configuration & Project Structure

Spring Framework (IoC container, AOP, data, security)
    ↑
Spring Boot (auto-config, embedded server, starter dependencies)
    ↑
Your application code

curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.4.0 \
  -d groupId=com.clinic \
  -d artifactId=portal-api \
  -d name=PortalApi \
  -d javaVersion=21 \
  -d dependencies=web,data-jpa,postgresql,security,validation,actuator \
  -o portal-api.zip && unzip portal-api.zip

src/main/java/com/clinic/portal/
├── PortalApiApplication.java       ← entry point
├── appointment/
│   ├── Appointment.java            ← JPA entity
│   ├── AppointmentRepository.java  ← Spring Data repo
│   ├── AppointmentService.java     ← business logic
│   ├── AppointmentController.java  ← REST controller
│   └── dto/
│       ├── AppointmentRequest.java
│       └── AppointmentResponse.java
├── patient/
│   ├── Patient.java
│   ├── PatientRepository.java
│   ├── PatientService.java
│   └── PatientController.java
├── security/
│   ├── SecurityConfig.java
│   ├── JwtAuthFilter.java
│   └── JwtService.java
└── common/
    ├── exception/
    │   └── GlobalExceptionHandler.java
    └── config/
        └── OpenApiConfig.java

// @Component — generic bean
@Component
public class EmailService { ... }

// @Service — business logic layer (semantic alias for @Component)
@Service
public class AppointmentService { ... }

// @Repository — data access layer (adds exception translation)
@Repository
public class AppointmentRepository { ... }

// @Controller / @RestController — web layer
@RestController
public class AppointmentController { ... }

// @Configuration + @Bean — manual bean declaration
@Configuration
public class AppConfig {
    @Bean
    public ObjectMapper objectMapper() {
        return new ObjectMapper()
            .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
            .registerModule(new JavaTimeModule());
    }
}

@Service
public class AppointmentService {

    private final AppointmentRepository repository;
    private final PatientService patientService;
    private final EmailService emailService;

    // Spring injects dependencies through the constructor
    // No @Autowired needed when there's only one constructor (Spring 4.3+)
    public AppointmentService(AppointmentRepository repository,
                               PatientService patientService,
                               EmailService emailService) {
        this.repository     = repository;
        this.patientService = patientService;
        this.emailService   = emailService;
    }
}

# src/main/resources/application.yml

spring:
  application:
    name: portal-api

  datasource:
    url: jdbc:postgresql://${DB_HOST:localhost}:5432/${DB_NAME:portal_dev}
    username: ${DB_USER:postgres}
    password: ${DB_PASSWORD:postgres}
    hikari:
      maximum-pool-size: 20
      connection-timeout: 30000

  jpa:
    hibernate:
      ddl-auto: validate       # never "create-drop" in prod
    show-sql: false
    properties:
      hibernate.format_sql: true

  security:
    jwt:
      secret: ${JWT_SECRET}
      expiration-ms: 3600000   # 1 hour

server:
  port: 8080
  shutdown: graceful
  error:
    include-message: never     # don't expose internals

management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, prometheus

# application-dev.yml
spring:
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update
  datasource:
    url: jdbc:postgresql://localhost:5432/portal_dev

logging:
  level:
    com.clinic: DEBUG

# application-prod.yml
spring:
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate

# Environment variable (recommended in production)
SPRING_PROFILES_ACTIVE=prod java -jar portal-api.jar

# Or as JVM arg
java -Dspring.profiles.active=prod -jar portal-api.jar

@ConfigurationProperties(prefix = "spring.security.jwt")
public record JwtProperties(String secret, long expirationMs) {}

// Register it
@SpringBootApplication
@EnableConfigurationProperties(JwtProperties.class)
public class PortalApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(PortalApiApplication.class, args);
    }
}

// Inject and use
@Service
public class JwtService {
    private final JwtProperties jwtProps;

    public JwtService(JwtProperties jwtProps) {
        this.jwtProps = jwtProps;
    }

    public String generateToken(String subject) {
        return Jwts.builder()
            .subject(subject)
            .expiration(new Date(System.currentTimeMillis() + jwtProps.expirationMs()))
            .signWith(Keys.hmacShaKeyFor(jwtProps.secret().getBytes()))
            .compact();
    }
}

java -jar portal-api.jar --debug 2>&1 | grep "AUTO-CONFIGURATION REPORT"

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })

@Component
public class StartupRunner implements ApplicationRunner {

    private final AppointmentRepository repo;

    public StartupRunner(AppointmentRepository repo) {
        this.repo = repo;
    }

    @Override
    public void run(ApplicationArguments args) throws Exception {
        long count = repo.count();
        log.info("Application started. {} appointments in database.", count);
    }
}