Spring Initializr has handed you a folder full of files you have probably not opened yet. Understanding what each one does is not a formality: most of the baffling problems of the early days —a controller returning 404, a property that is never read, a dependency that fails to appear— are explained by the project structure and by where you put a class. In this lesson we will walk through the directory tree, read the pom.xml line by line, see what a starter really is, understand why the root package is critical and settle CicloUrbana's definitive package layout.

1. The generated directory tree
2. src/main/java and src/main/resources
3. src/test/java, target/ and the Maven wrapper
4. Anatomy of the pom.xml, line by line
5. What a starter is and which ones we will use in the course
6. The root package and component scanning
7. Organising the code: by layer or by feature
8. CicloUrbana's package structure
9. The Maven lifecycle
10. Common Mistakes and Tips
11. Exercises

This is the project exactly as it stands after the previous lesson:

This layout is not a Spring Boot invention: it is the standard Maven layout, honoured across the whole Java ecosystem. The practical consequence is that any Java developer can find their way around your project without explanations.

The fundamental split is between main (what gets packaged and deployed) and test (what runs during the build but never reaches the JAR).

Holds all the production source code. The folder structure must mirror the package structure exactly: the class com.ciclourbana.stations.StationController has to live in src/main/java/com/ciclourbana/stations/StationController.java. This is not an optional convention; the Java compiler demands it.

Holds the non-compilable files that must end up inside the JAR. Maven copies them verbatim into target/classes, which means that at runtime they sit at the root of the classpath.

Two important details:

• static/: any file you drop in here is served automatically from the root. A static/logo.png is reachable at http://localhost:8080/logo.png. A Spring Web autoconfiguration makes that happen.
• templates/: only makes sense if you add a template engine. CicloUrbana is a pure REST API, so this folder will stay empty. You can delete it with no consequences.

It starts out empty. Let us give it something useful right away:

Every line is a key=value pair. Spring Boot defines hundreds of keys with sensible defaults; here you only declare the ones where you want to depart from those defaults. Lesson 02-05 goes deeper into properties, including the YAML alternative.

Holds the tests. Initializr generates one:

Even with an empty body, this test is not useless: @SpringBootTest starts the full Spring context. If a dependency is missing, a bean cannot be constructed or a mandatory property is absent, the test fails. It is a very cheap smoke check that catches configuration errors before deployment. Module 6 is devoted entirely to testing.

Test classes are not included in the final JAR.

This is Maven's output folder. It is regenerated in full with every build, which is why it sits in the .gitignore and must never be versioned.

When something behaves inexplicably, ./mvnw clean deletes target and removes the leftovers of earlier builds. It is the first remedy to try.

You already met them in lesson 01-02. The relevant content:

These three files do belong in Git: they are what guarantees that anyone builds the project with the same Maven version.

The pom.xml (Project Object Model) is the heart of the project. Let us read it in full.

By some distance this is the most important block and the least well understood. It brings four things:

1. Version management (dependencyManagement). It declares the right version for more than 250 libraries —Spring, Jackson, Hibernate, Tomcat, JUnit, Mockito, Log4j...— tested and validated to work together for that Boot release. That is why your dependencies carry no <version>: they inherit it from here. This wipes out at a stroke the version conflicts that used to plague Java projects.
2. Plugin configuration. It pre-configures the compiler, the resources plugin, Surefire (tests) and the spring-boot-maven-plugin.
3. Sensible defaults. UTF-8 encoding for sources and resources, and the Java version taken from the java.version property.
4. Resource filtering. It lets you use @property@ inside application.properties to inject values from the pom.xml.

You can see the full list of managed versions:

That command shows the "effective" POM: yours merged with everything it inherits from the parent. The first time, it is striking to see how much work those five lines are saving you.

The parentless alternative: if your organisation already has its own corporate parent POM, you can import just the version management through the BOM (Bill of Materials):

Every Java library is identified by three values:

The -SNAPSHOT suffix means "under development, may change". Maven treats snapshots specially: it re-downloads them periodically instead of caching them forever. When you publish a stable release you drop the suffix (1.0.0).

The three coordinates determine the JAR's name: ciclourbana-0.0.1-SNAPSHOT.jar.

java.version is read by the parent to configure the compiler with -source 21 -target 21. Here you can define your own variables and use them with the ${name} syntax:

That dependency does carry a <version> because it is not managed by the Spring Boot parent: it is a third-party library. It is the exception that proves the rule.

The <scope> element decides when a dependency is available:

spring-boot-devtools combines runtime with <optional>true</optional>: you do not compile against it, it is not propagated to projects that depend on yours, and Spring Boot switches it off when it detects that it is running from a fat jar.

This is the plugin that turns an ordinary JAR into the executable fat jar. It provides:

• The repackage goal, bound to the package phase, which repackages the JAR with BOOT-INF/ and the JarLauncher.
• The spring-boot:run goal, which starts the application without packaging it.
• The build-image goal, which builds a Docker image without writing a Dockerfile (module 7).

Without this plugin, ./mvnw package would produce a 12 KB JAR that is useless on its own.

A starter is a Maven dependency with no code of its own: just a pom.xml declaring a coherent set of dependencies. Its value is that somebody has already decided for you which libraries you need and at which versions.

See for yourself:

Abridged output:

One line in your pom.xml has turned into more than thirty coordinated artefacts.

Notice spring-boot-starter: it is the base starter that all the others depend on. It brings the core, autoconfiguration and the logging system. It is always present even if you never declare it.

These are the starters that will appear in CicloUrbana:

There are third-party starters too, which by convention reverse the order of the name: the official ones are spring-boot-starter-* and third-party ones are <name>-spring-boot-starter (mybatis-spring-boot-starter, for instance).

Here lies the cause of one of the beginner's most frustrating errors.

The @SpringBootApplication annotation includes @ComponentScan, which tells Spring: "look for classes annotated with @Component, @Service, @Repository, @Controller or @RestController starting from this class's package and downwards".

CicloUrbanaApplication sits in com.ciclourbana, so Spring scans com.ciclourbana and all its subpackages. Anything outside is invisible.

The typical symptom is a 404 on an endpoint whose code looks flawless: the controller exists but Spring never registered it, because it sat outside the scanned tree.

Practical rules:

1. Always place CicloUrbanaApplication in the root package, above every feature package.
2. Never put it in the default package (with no package statement). Spring would scan the entire classpath, which blows up startup time and causes unpredictable errors. Spring Boot warns about this explicitly.
3. If you need to scan an external package —a shared library from your company—, widen the scan:

This is the concrete reason why "the main class goes in the root package" is not an aesthetic quirk but an operational requirement.

There are two ways to structure the packages, and the choice shapes the project's maintainability for years.

CicloUrbana will be organised by feature. The decisive reason is the last row of the table: in module 7 we will talk about microservices, and with this structure extracting "rentals" into a standalone service is little more than copying a folder.

This is the definitive layout the project will fill in module by module:

A description of each package and the module in which it gets filled:

The dotted arrows in the diagram show the legitimate dependencies between packages. One rule worth honouring from the start: the common package must not depend on any feature package. If common imports something from rentals, it stops being common and you get circular dependencies that are hard to unpick.

For now only stations exists, with Station and StationController. That is as it should be: packages are created when there is something to put inside them, not before.

Maven organises the build into ordered phases. Invoking a phase runs every phase before it.

clean belongs to a different lifecycle, which is why it is combined explicitly:

About -DskipTests: it compiles the tests but does not run them. There is also -Dmaven.test.skip=true, which does not even compile them and therefore hides compilation errors in the test code. Prefer the first one.

• Putting the controller outside the root package. It is the number one cause of "my endpoint returns 404 and I don't understand why". Always check that the class's package starts with com.ciclourbana.
• Adding a <version> to dependencies the parent manages. You break the coherence of the set and you may trigger a NoSuchMethodError at runtime, an error that is especially hard to diagnose.
• Versioning the target folder. It clutters the repository with megabytes of regenerable artefacts. Initializr's .gitignore already excludes it; leave it alone.
• Confusing src/main/resources with src/main/java. An application.properties placed in src/main/java is not copied onto the classpath and is simply ignored, with no warning whatsoever.
• Not versioning mvnw and .mvn/. After cloning, nobody could build without installing Maven. They belong in Git.
• Tip — inspect the dependency tree. ./mvnw dependency:tree answers "where does this library come from?" and exposes version conflicts. It is Maven's most useful diagnostic tool.
• Tip — run help:effective-pom once. Seeing the effective POM makes it instantly clear what the parent is doing for you.
• Tip — one package per business concept, not per technology. If you find yourself creating a utils package that grows out of control, it is a sign that a domain concept is waiting to be identified.

Run ./mvnw dependency:tree on your project and answer: how many artefacts does spring-boot-starter-web pull in? Which embedded Tomcat version is in use? Which starter does Jackson come from?

Deliberately reproduce the root-package error: move StationController into the package com.othercompany.web, start the application and see what happens. Then fix it in two different ways and explain which one is preferable.

Prepare CicloUrbana's package structure by creating the planned empty packages and a package-info.java in each one documenting its responsibility. Justify why common must not depend on any other package.

Solution 1

Typical answers with Spring Boot 3.3.5:

• Number of artefacts: around 30 transitive dependencies. You can count them with:

• Embedded Tomcat: org.apache.tomcat.embed:tomcat-embed-core:10.1.31. That is Tomcat 10.1, the first branch to use the jakarta.* namespace, consistent with Spring Boot 3.
• Jackson: it arrives through spring-boot-starter-json, which is in turn a dependency of spring-boot-starter-web. The chain is:

This explains why the endpoint from the previous lesson returned JSON without your adding any dependency: it came bundled.

Solution 2

After moving the class:

The application starts with no error at all —that is the disconcerting part— but:

The controller was never registered because component scanning never visited com.othercompany.web.

Fix 1: widen the scan.

Fix 2: put the class back where it belongs.

The second is clearly preferable. The first works, but it introduces an exception to the convention that has to be remembered and documented; over time more stray packages appear and scanning becomes unpredictable. Widening scanBasePackages is justified only when integrating an external library whose package you cannot change.

Solution 3

An example package-info.java, a special Java file whose only job is to document a package:

And the one for the common package:

The rationale behind the rule: common is the foundation the other packages rest on. If it depended on rentals, a cycle would appear (rentals → common → rentals) with three serious consequences: it would be impossible to reason about initialisation order, common could not be extracted into a reusable library, and any change in rentals would force a recompilation and retest of practically the whole project. Dependencies must always flow from the specific to the general, never the other way round.

There are no mysterious files left in the project. You know what lives in src/main/java, src/main/resources, src/test/java and target; you have read the whole pom.xml and you understand that the parent is what manages the versions of more than two hundred libraries, that a starter is a curated list of dependencies with no code of its own, and that the spring-boot-maven-plugin is what manufactures the fat jar. Above all, you know why CicloUrbanaApplication must live in the root package: component scanning starts there, and anything outside will be invisible to Spring. And you have settled the feature-based structure —stations, bikes, rentals, users, security, common— that will stay with the project all the way to module 10.

In the next lesson, Application Startup and Lifecycle, we will step inside SpringApplication.run(...) to see exactly what happens between pressing Run and the appearance of "Started CicloUrbanaApplication": context creation, scanning, autoconfiguration, the Tomcat startup and the events you can hook into to run your own code at precisely the right moment.