Beginner

// Standard library approach: packages group code but enforce no boundary
// Illustrative snippet — not from apps/organiclever-be; demonstrates the stdlib
// package approach that the hexagonal context layout supersedes.
 
package com.organicleverbe.gap;
 
// Direct import from another context's infrastructure — no barrier here
import com.organicleverbe.task.infrastructure.TaskJpaRepository;
// => Java allows cross-package imports unconditionally
// => The compiler sees no violation even though gap analysis is
//    reading task infrastructure internals directly
// => Any refactor of TaskJpaRepository silently breaks GapAnalysis
 
public class GapService {
    private final TaskJpaRepository taskRepo; // infrastructure type leaking into a domain service
    // => GapService now depends on a Spring Data JPA interface
    // => Unit testing GapService requires a full Spring context or a mock of TaskJpaRepository
    // => The boundary exists only in the developer's head
}

// Intended layout — task context domain layer
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/domain/
 
package com.organicleverbe.task.domain;
 
// => Package path mirrors the hexagonal layer: task context, domain layer
// => No Spring imports anywhere in this file — records are pure Java SE
 
public record TaskId(java.util.UUID value) {
    // => Strongly-typed wrapper: prevents passing a gap ID where a task ID is expected
    // => Java record provides equals, hashCode, toString automatically
    // => Compact constructor can add validation if needed (e.g., null check)
    public TaskId {
        java.util.Objects.requireNonNull(value, "TaskId value must not be null");
        // => Canonical constructor validation — throws NullPointerException if null
    }
}
 
public record Task(
    TaskId id,           // => Aggregate identity — drives equality
    String title,        // => Ubiquitous language field: what the task is called
    String ownerId,      // => Foreign key to the user context — no User object imported
    boolean completed    // => Simple boolean state — no ORM annotation here
) {}
// => Plain Java record: immutable, no @Entity, no @Column, no Jackson @JsonProperty
// => The ORM mapping lives in the infrastructure layer (Guide 7)
// => The serialization mapping lives in the presentation layer (Guide 6)

// Current flat layout: OrganicleverBeApplication.java — Spring Boot bootstrap
package com.organicleverbe;
// => Root package: Spring component scan starts here and covers all sub-packages
// => @SpringBootApplication covers @Configuration + @EnableAutoConfiguration + @ComponentScan
 
import org.springframework.boot.SpringApplication;
// => SpringApplication: utility class that bootstraps a Spring application from a main method
import org.springframework.boot.autoconfigure.SpringBootApplication;
// => SpringBootApplication: meta-annotation combining @Configuration, @EnableAutoConfiguration,
//    and @ComponentScan — one annotation to start the whole context
 
@SpringBootApplication
// => Triggers auto-configuration for everything on the classpath: Spring MVC,
//    Jackson, Actuator, DevTools — no explicit setup needed for defaults
public class OrganicleverBeApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrganicleverBeApplication.class, args);
        // => SpringApplication.run bootstraps the ApplicationContext
        // => The class argument tells Spring Boot which package to scan from
        // => Args forwarded: supports --server.port, --spring.profiles.active, etc.
    }
}

// Current config: CorsConfig.java — cross-cutting infrastructure configuration
package com.organicleverbe.config;
// => config/ package holds cross-cutting infrastructure concerns: CORS, exception handling
// => This package is not a bounded context — it is the application's wiring layer
 
import org.springframework.context.annotation.Configuration;
// => @Configuration import: required for the Spring @Configuration annotation below
import org.springframework.web.servlet.config.annotation.CorsRegistry;
// => CorsRegistry: Spring MVC fluent API for registering CORS mappings per path pattern
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
// => WebMvcConfigurer: callback interface for customizing Spring MVC configuration
 
@Configuration
// => @Configuration marks this as a Spring bean factory: methods annotated with @Bean
//    produce beans registered in the ApplicationContext
public class CorsConfig implements WebMvcConfigurer {
    // => Implements WebMvcConfigurer: overrides only the addCorsMappings callback
    // => Spring MVC detects @Configuration classes implementing this interface automatically
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        // => WebMvcConfigurer hook: customizes Spring MVC configuration
        // => addCorsMappings runs during context startup, before any request arrives
        registry.addMapping("/**")
                // => /** wildcard: applies CORS policy to every endpoint
                .allowedOrigins("*")
                // => allowedOrigins("*"): accepts requests from any origin
                // => Production should scope this to specific frontend domains
                .allowedMethods("*")
                // => allowedMethods("*"): permits GET, POST, PUT, DELETE, OPTIONS, etc.
                .allowedHeaders("*");
                // => allowedHeaders("*"): no restriction on custom headers
    }
}

// Standard library: pure Java record, zero framework annotations
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/domain/
 
package com.organicleverbe.task.domain;
// => Domain package: no Spring, no JPA, no Jackson imports allowed here
 
import java.util.Objects;
// => Objects.requireNonNull: standard null guard — throws NullPointerException on null
import java.util.UUID;
// => UUID: java.util identity type — no framework dependency needed for aggregate IDs
 
public record Task(
    TaskId id,
    // => Strongly-typed identity — prevents confusion with other aggregate IDs
    // => TaskId wraps UUID: the compiler rejects a raw UUID where a TaskId is expected
    String title,
    // => Ubiquitous language: what the task is in business terms
    // => String: plain text title — bounded-context language uses "title", not "name" or "description"
    String ownerId,
    // => Reference to user context by ID only — no User object imported
    // => Cross-context coupling via primitive ID: the task context never imports the user domain type
    boolean completed
    // => Simple boolean state — no ORM column mapping annotation
    // => false at creation: the compact constructor enforces this invariant through the creation path
) {
    // => Java record compact constructor: runs before each component is assigned
    // => All validation happens here — the record is immutable after construction
    public Task {
        Objects.requireNonNull(id, "Task id must not be null");
        // => Null guard for identity — throws NullPointerException at construction time
        Objects.requireNonNull(title, "Task title must not be null");
        // => Null guard for required field — invariant enforced at the domain boundary
        if (title.isBlank()) throw new IllegalArgumentException("Task title must not be blank");
        // => Domain invariant: a task without a title violates the ubiquitous language
        Objects.requireNonNull(ownerId, "Task ownerId must not be null");
        // => Every task must have an owner — no orphan tasks in the domain model
    }
}

// GlobalExceptionHandler.java — Spring exception mapping in the config layer, not domain
package com.organicleverbe.config;
// => config/ is the infrastructure/framework wiring layer — not a domain package
 
import org.springframework.http.HttpStatus;
// => HttpStatus: enum of HTTP status codes — used to set the response status
import org.springframework.http.ProblemDetail;
// => ProblemDetail: RFC 9457 / HTTP Problem Details — Spring 6+ standard error response format
import org.springframework.web.bind.annotation.ExceptionHandler;
// => @ExceptionHandler: marks a method as an exception handler for specific exception types
import org.springframework.web.bind.annotation.RestControllerAdvice;
// => @RestControllerAdvice: combines @ControllerAdvice and @ResponseBody for all @RestControllers
 
@RestControllerAdvice
// => @RestControllerAdvice: applies @ExceptionHandler methods to all @RestControllers
// => This is infrastructure wiring — it lives in config/, not in any bounded context domain package
// => Domain exceptions (e.g., TaskNotFoundException) bubble up; this class translates them to HTTP
public class GlobalExceptionHandler {
 
    @ExceptionHandler(Exception.class)
    // => Catch-all handler: covers any exception not matched by a more specific @ExceptionHandler
    // => More specific handlers (e.g., for domain exceptions) can be added here without touching domain code
    public ProblemDetail handleGenericException(Exception ex) {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
        // => ProblemDetail.forStatus: produces an RFC 9457 JSON body with status 500
        // => The domain never produces ProblemDetail — that is this layer's responsibility
        problem.setDetail(ex.getMessage());
        // => ex.getMessage() surfaces the exception message in the error response
        // => Production: scrub sensitive messages before surfacing to clients
        return problem;
        // => Spring serializes ProblemDetail to application/problem+json automatically
    }
}

// Standard library: application service as a plain interface with domain types only
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/application/
 
package com.organicleverbe.task.application;
// => application/ package: orchestration contracts and service interfaces
// => No Spring imports — the interface is framework-agnostic
 
import com.organicleverbe.task.domain.Task;
// => Task: the domain aggregate — the service returns fully validated Task records
import com.organicleverbe.task.domain.TaskId;
// => TaskId: the strongly-typed identity — prevents raw String/UUID passing at the boundary
// => Domain types only: the application service talks in domain terms
import java.util.Optional;
// => Optional for absence: find returns Optional<Task>, not null
 
public interface TaskApplicationService {
    // => Java interface: the contract without the implementation
    // => The implementation (the @Service class) lives in infrastructure/
 
    Task createTask(String title, String ownerId);
    // => Parameters are primitives — the smart constructor inside this method
    //    builds the aggregate and enforces invariants
    // => Returns the full domain aggregate, not a response DTO
 
    Optional<Task> findById(TaskId id);
    // => Optional<Task>: absence is a valid domain outcome, not null
    // => TaskId is a strongly-typed domain value — not a raw UUID or String
    // => The controller translates absent -> 404, present -> 200 + DTO
 
    Task markCompleted(TaskId id);
    // => Returns the updated aggregate — the controller translates to 200 + DTO
    // => Throws a domain exception (e.g., TaskNotFoundException) if not found
    // => The GlobalExceptionHandler translates domain exceptions to HTTP status codes
}

// Intended production application service interface with typed exceptions
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/application/
 
package com.organicleverbe.task.application;
 
import com.organicleverbe.task.domain.Task;
import com.organicleverbe.task.domain.TaskId;
// => Only domain types imported — no Spring, no Jakarta, no Jackson
import java.util.Optional;
 
public interface TaskApplicationService {
    // => Pure Java interface: zero Spring coupling
    // => Spring injects the @Service implementation at startup via constructor injection
    // => The controller declares this interface type — it never imports the @Service class
 
    Task createTask(String title, String ownerId) throws DuplicateTaskException;
    // => Typed exception: DuplicateTaskException signals a business rule violation
    // => The GlobalExceptionHandler (or a specific @ExceptionHandler) maps it to HTTP 409
    // => Declared in the throws clause: callers are aware of this outcome at compile time
 
    Optional<Task> findById(TaskId id);
    // => No checked exception: absence is not an error — it is returned as Optional.empty()
    // => The controller decides whether Optional.empty() means 404 or something else
 
    Task markCompleted(TaskId id) throws TaskNotFoundException;
    // => TaskNotFoundException: a business rule violation — you cannot complete a nonexistent task
    // => The @ExceptionHandler maps this to HTTP 404 with a domain-meaningful message
    // => Keeping the exception in the application package keeps it reusable across controllers
}

// Standard library: output port as a plain Java interface
// Illustrative snippet — not from apps/organiclever-be; demonstrates the stdlib
// interface pattern that the Spring @Component adapter satisfies.
 
package com.organicleverbe.task.application;
 
import com.organicleverbe.task.domain.Task;
import com.organicleverbe.task.domain.TaskId;
// => Only domain types in the application package — no JPA, no JDBC
 
import java.util.Optional;
 
public interface TaskRepository {
    // => Java interface as output port: declares what the application layer needs
    // => No implementation here — the infrastructure adapter provides it
    // => This interface is the only thing the application service knows about persistence
 
    void save(Task task);
    // => Write-side port: persist a domain aggregate
    // => void: the service trusts the adapter to persist atomically
    // => Throws RuntimeException subtypes (e.g., DataAccessException) on failure
 
    Optional<Task> findById(TaskId id);
    // => Read-side port: retrieve by identity
    // => Optional wraps absence — the service does not receive null
    // => The adapter queries the DB and maps the result to a domain Task record
}

// Intended production output port — application package
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/application/
 
package com.organicleverbe.task.application;
 
import com.organicleverbe.task.domain.Task;
import com.organicleverbe.task.domain.TaskId;
// => Only domain types imported — the interface is entirely in domain and stdlib terms
 
import java.util.List;
import java.util.Optional;
 
public interface TaskRepository {
    // => Output port interface declared in application/ — not in infrastructure/
    // => The @Repository adapter in infrastructure/ implements this interface
    // => The application service's constructor parameter is this interface type
 
    void save(Task task);
    // => Write-side operation: persist or update the aggregate
    // => Throws TaskPersistenceException (a domain-adjacent exception) on infrastructure failure
    // => The GlobalExceptionHandler maps TaskPersistenceException to HTTP 500
 
    Optional<Task> findById(TaskId id);
    // => Read-side operation: returns Optional.empty() when the task does not exist
    // => Optional communicates absence without null — no NullPointerException risk
 
    List<Task> findByOwnerId(String ownerId);
    // => Query port operation: returns all tasks for a given owner
    // => List is empty (not null) when the owner has no tasks
    // => The adapter may page results in production; the interface can be extended
 
    void delete(TaskId id);
    // => Soft-delete or hard-delete — the adapter decides; the interface does not commit
    // => Throws TaskNotFoundException if the task does not exist
}

// Standard library: plain HttpServlet without Spring MVC
// Illustrative snippet — not from apps/organiclever-be; demonstrates the
// stdlib servlet pattern that Spring @RestController supersedes.
 
import jakarta.servlet.http.HttpServlet;
// => HttpServlet: base class for servlets — subclass and override doGet, doPost, etc.
import jakarta.servlet.http.HttpServletRequest;
// => HttpServletRequest: provides access to the HTTP request (method, headers, body, params)
import jakarta.servlet.http.HttpServletResponse;
// => HttpServletResponse: provides access to the HTTP response (status, headers, body)
// => Jakarta Servlet API: the lowest-level HTTP contract in Java EE / Jakarta EE
import java.io.IOException;
// => IOException: thrown by getWriter().write() — must be declared or caught
 
public class HealthServlet extends HttpServlet {
    // => HttpServlet: subclass and override doGet, doPost, etc.
    // => No automatic JSON serialization — you write to the output stream manually
    // => No routing: the servlet container maps URLs to servlet classes via web.xml or @WebServlet
 
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws IOException {
        // => Override per-method: doGet, doPost, doPut, doDelete are separate overrides
        // => throws IOException: propagates write failures to the servlet container
        resp.setContentType("application/json");
        // => Set content type manually — no automatic negotiation
        resp.setStatus(HttpServletResponse.SC_OK);
        // => Set status code explicitly: 200 OK
        resp.getWriter().write("{\"status\":\"UP\"}");
        // => Write JSON string manually — no object-to-JSON conversion
        // => A Jackson ObjectMapper call would replace this, but that is extra ceremony
    }
}

// Spring @RestController — primary (driving) adapter
package com.organicleverbe.health.controller;
// => health/controller/ package: flat layout predating the hexagonal migration
// => In the intended layout this would be: com.organicleverbe.health.presentation/
 
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
// => Spring MVC annotations: @RestController = @Controller + @ResponseBody
// => @RequestMapping sets the base URL path for all methods in this class
// => @GetMapping is shorthand for @RequestMapping(method = RequestMethod.GET)
 
import java.util.Map;
// => Map.of() is used for the response — no DTO record needed for a trivial health check
 
@RestController
// => @RestController: Spring registers this as an HTTP handler; serializes return values to JSON
// => No explicit @ResponseBody needed: @RestController implies it for all methods
@RequestMapping("/api/v1")
// => Base path: all mappings in this class are relative to /api/v1
public class HealthController {
 
    @GetMapping("/health")
    // => GET /api/v1/health: no path variable, no request body, no authentication
    // => Spring MVC resolves this mapping during context startup — no runtime routing table needed
    public Map<String, String> health() {
        // => Return type Map<String, String>: Jackson serializes this to {"status":"UP"}
        // => No ResponseEntity wrapper: Spring MVC uses the return type to set 200 OK
        return Map.of("status", "UP");
        // => Map.of: immutable single-entry map — Java 9+ standard library
        // => "status" key matches the expected health check response format
    }
}

// Intended production controller for a domain command
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/presentation/
 
package com.organicleverbe.task.presentation;
 
import com.organicleverbe.task.application.TaskApplicationService;
import com.organicleverbe.task.application.DuplicateTaskException;
// => Application layer interface and exception — not the @Service implementation
// => The controller is decoupled from the concrete adapter class
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
// => Spring MVC annotations only — no JPA, no domain imports in the annotation block
 
public record CreateTaskRequest(String title, String ownerId) {}
// => Request DTO as a Java record: immutable, no validation annotations at this level
// => Validation could use Jakarta Bean Validation (@NotBlank) — added in production
// => Lives in the presentation package — domain never imports this type
 
public record TaskResponse(String id, String title, String ownerId, boolean completed) {}
// => Response DTO: maps domain aggregate fields to JSON-serializable types
// => String id: UUID converted to String for JSON — domain uses TaskId record
// => The application service never produces or consumes this type
 
@RestController
// => @RestController: combines @Controller and @ResponseBody — all methods return JSON
@RequestMapping("/api/v1/tasks")
// => Base path scoped to the task context — each context owns its URL prefix
public class TaskController {
 
    private final TaskApplicationService taskService;
    // => Constructor injection: Spring Boot injects the @Service implementation at startup
    // => Field is final: immutable after construction — thread-safe by default
    // => Interface type declared here — the controller never imports the concrete @Service class
 
    public TaskController(TaskApplicationService taskService) {
        this.taskService = taskService;
        // => No @Autowired annotation needed: Spring Boot auto-detects single-constructor injection
        // => Declaring the interface type means the controller works with any adapter implementation
    }
 
    @PostMapping
    // => @PostMapping: handles HTTP POST to /api/v1/tasks — no extra path segment needed
    public ResponseEntity<TaskResponse> createTask(@RequestBody CreateTaskRequest request) {
        // => @RequestBody: Jackson deserializes the HTTP request body into CreateTaskRequest
        // => Returns ResponseEntity to control the HTTP status code explicitly
        var task = taskService.createTask(request.title(), request.ownerId());
        // => Translate DTO -> domain call: title and ownerId are raw strings here
        // => The application service builds the Task aggregate with invariant validation
        // => On success: task is a valid domain aggregate
        var response = new TaskResponse(
            task.id().value().toString(),
            // => task.id().value(): unwrap TaskId -> UUID -> String for JSON
            task.title(),
            task.ownerId(),
            task.completed()
            // => Map each domain field to the response DTO — one mapping, one place
        );
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
        // => HTTP 201 Created: the standard status for successful resource creation
        // => body(response): Spring MVC / Jackson serializes TaskResponse to JSON
    }
}

// Standard library: manual composition root in main()
// Illustrative snippet — not from apps/organiclever-be; demonstrates the
// manual DI pattern that Spring @Configuration supersedes.
 
public class Application {
    public static void main(String[] args) {
        // => Composition root: all concrete types constructed here
        // => The rest of the codebase only sees interfaces
 
        var taskRepository = new InMemoryTaskRepository();
        // => Concrete adapter chosen at startup — swap to JpaTaskRepository for production
        // => No @Autowired magic: the dependency is explicit and visible
 
        var taskService = new TaskApplicationServiceImpl(taskRepository);
        // => Constructor injection: taskService receives the interface, not the concrete class
        // => Changing the adapter means changing only this line
 
        var taskController = new TaskController(taskService);
        // => Controller receives the service interface — it does not know about InMemory or JPA
        // => The entire wiring is visible in one place: this main method
    }
}

// Current entry point: OrganicleverBeApplication.java
package com.organicleverbe;
// => com.organicleverbe: root package — Spring Boot scans from here
 
import org.springframework.boot.SpringApplication;
// => SpringApplication: entry-point bootstrap utility — run() starts the entire ApplicationContext
import org.springframework.boot.autoconfigure.SpringBootApplication;
 
@SpringBootApplication
// => @SpringBootApplication triggers component scan from this package downward
// => Every @Component, @Service, @Repository, @RestController in sub-packages is registered
// => Auto-configuration reads the classpath: spring-boot-starter-web adds DispatcherServlet,
//    Jackson ObjectMapper, and Tomcat embedded server automatically
public class OrganicleverBeApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrganicleverBeApplication.class, args);
        // => SpringApplication.run: bootstraps ApplicationContext, starts embedded Tomcat,
        //    runs CommandLineRunner/ApplicationRunner beans, and begins accepting requests
        // => args forwarded to Spring: --server.port=8080, --spring.profiles.active=prod, etc.
    }
}

// Intended production @Configuration — composition root for the task context
// New file — intended layout, scaffolding exists at
// apps/organiclever-be/src/main/java/com/organicleverbe/task/infrastructure/
 
package com.organicleverbe.task.infrastructure;
 
import com.organicleverbe.task.application.TaskApplicationService;
import com.organicleverbe.task.application.TaskRepository;
// => Application layer interfaces imported — not domain or presentation types
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
// => @Configuration: marks this as a Spring bean factory
// => @Bean: each annotated method produces a bean registered in the ApplicationContext
 
@Configuration
// => Spring registers this class during component scan
// => All @Bean methods in this class are called once at startup to build the context
public class TaskContextConfiguration {
 
    @Bean
    // => @Bean: Spring calls this method and registers the return value as a singleton
    public TaskRepository taskRepository() {
        return new TaskJpaAdapter();
        // => Concrete adapter chosen here — in tests, replace this @Configuration
        //    with a test @Configuration that returns new InMemoryTaskRepository()
        // => The application service never sees TaskJpaAdapter — it receives TaskRepository
    }
 
    @Bean
    public TaskApplicationService taskApplicationService(TaskRepository taskRepository) {
        // => Spring injects the TaskRepository bean produced above
        // => Constructor injection: explicit, visible, testable
        // => No @Autowired on the service class — the wiring is declared here
        return new TaskApplicationServiceImpl(taskRepository);
        // => TaskApplicationServiceImpl is the @Service implementation
        // => It receives the interface, not the concrete adapter
    }
}