Project structure · Backend
Spring Boot project structure
Opens with creditsA REST API in Java with Spring Boot 4, PostgreSQL, Flyway and Testcontainers, organised by feature the way the Spring docs suggest. It grows from the Initializr scaffold to a service with JWT security, problem-detail errors, MapStruct DTOs, slice and integration tests, CI, containers and observability, and finally Modulith boundaries, contract and load tests. For students who know some Java and want to see how a real service is organised.
Curated by Tauseef FayyazIntermediate183 files and foldersSpring Boot 4.1, Spring Framework 7, Spring Security 7.1Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you40 files and folders
- 2GrowingWhat a real app with features and tests adds+64 files and folders
- ProductionWhat running it for real users adds+36 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+43 files and foldersOpens with credits
How it is organised
- Put the class with @SpringBootApplication in the root package (com.example.shop). Component scanning and entity scanning start there, so everything else must live below it.
- Package by feature, not by layer: order/ holds the order controller, service, repository, entity, mapper and DTOs. The Spring Boot docs show this layout, and it keeps a change to one feature inside one folder.
- Keep the layers inside each feature: controller (HTTP) calls service (rules and transactions) calls repository (database). Controllers never touch repositories, and features talk through public services or events, never through each other's tables.
- Never return JPA entities from controllers. Map them to records with MapStruct so the API does not change every time a column does.
- The database schema belongs to Flyway migrations, not to Hibernate. Set ddl-auto to validate and add a new V<n>__ file for every change; seed data lives in a separate location only the dev profile loads.
- Configuration lives in application.yaml with profile files on top, bound to validated @ConfigurationProperties records, and secrets come from environment variables, never from committed files.
- Test each layer with the cheapest test that proves it: Mockito for services, @WebMvcTest and @DataJpaTest slices, a few @SpringBootTest integration tests, all against real PostgreSQL with Testcontainers instead of H2.
- Add Expert tooling (Modulith, ArchUnit, Pact, Gatling, mutation tests, release automation) when the team and the number of consumers grow, not on day one. One Maven module with enforced package boundaries goes a long way before a multi-module build pays off.
At the top of the project
Open one in the explorer for the full story
- shop/
- .devcontainer/A dev container: Java 25, Maven and Docker-in-Docker, ready in VS Code or Codespaces.1 inside
- .mvn/Settings for the Maven Wrapper, so everyone builds with the same Maven version.1 inside
- .vscode/Shared VS Code settings, recommended extensions and launch configurations.3 inside
- config/Build tool configuration files referenced from pom.xml: Checkstyle rules, scan suppressions.1 inside
- src/All source code, configuration and tests, in the standard Maven layout.2 inside
- target/Maven build output: compiled classes, generated mappers, test and coverage reports, the jar.
- .editorconfigIndentation, charset and line endings for every editor and IDE.
- .envLocal secrets and settings for Docker Compose and your run configuration. Never committed.
- .env.exampleEvery environment variable the app needs, with fake values. Committed.
- .gitattributesFixes line endings: LF for mvnw, CRLF for mvnw.cmd.
- .git-blame-ignore-revsCommits that only reformatted code, hidden from git blame.
- .gitignoreKeeps build output and IDE files out of Git.
- .sdkmanrcPins the JDK for SDKMAN users: java=25-tem.
- AGENTS.mdInstructions for AI coding agents: commands, layout rules and what never to do.
- CLAUDE.mdClaude Code's project instructions, one line importing AGENTS.md.
- compose.yamlLocal PostgreSQL for development, started automatically when you run the app.
- HELP.mdLinks to the docs for each dependency you picked on Initializr.
- lefthook.ymlGit hooks: Spotless on staged Java files before commit, a commit message check.
- mvnwMaven Wrapper script for macOS and Linux: downloads the pinned Maven and runs it.
- mvnw.cmdThe same wrapper for Windows Command Prompt and PowerShell.
- pom.xmlMaven build file: Java version, dependencies, plugins, and later quality and release profiles.
- README.mdWhat the service does and how to run, test and deploy it.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Spring Boot.
- Roadmap· JavaBackend development roadmapAPIs, databases, auth, deploys
- Roadmap· Spring Boot and ReactFull stack development roadmapBuild and ship whole web apps
- Roadmap· PostgreSQLSQL and databases roadmapQueries, design, indexes, transactions
- RoadmapQA and test automation roadmapManual testing to automated suites
- Cheat sheetBackend development cheat sheetAPIs, databases, auth, deploys.
- Cheat sheetSQL and databases cheat sheetQueries, design, indexes, transactions.
- Cheat sheetQA and test automation cheat sheetManual testing to automated suites.
- Cheat sheetDevOps and cloud cheat sheetLinux, Docker, Kubernetes, AWS.
- FYP idea· AdvancedDouble-Entry Ledger Service for Marketplace Wallets and PayoutsA double-entry ledger service for marketplaces and wallet apps that records every rupee or dollar as balanced entries, handles holds, refunds and seller payouts, and proves its balances are correct. A fintech final year project in systems design, idempotency and concurrency, modelled on how Stripe and Uber track money movement.
See 11 moreShow fewer
- FYP idea· BeginnerAutomated Backup Restore Drills for Small Business DatabasesA backup service for small businesses that does not stop at taking backups: it restores them on a schedule into a throwaway container, checks the data and reports how long recovery really takes. A practical cloud and DevOps final year project for shops, clinics and agencies running MySQL, PostgreSQL or MongoDB on a single server.
- FYP idea· AdvancedSigned, Staged OTA Updates with Automatic Rollback for ESP32 Device FleetsBuild a self-hostable update system for small fleets of ESP32 devices that signs every firmware image, rolls updates out in stages, checks device health after each update and rolls back automatically when something goes wrong. Small IoT companies in Pakistan and elsewhere ship devices with no safe way to fix bugs in the field, or with update schemes that a single bad build can brick. The project applies the security ideas behind automotive update frameworks at a scale a startup can run.
- QuestionHow do I learn to read a large codebase when I can handle small projects but get lost in real ones?Nobody reads a large codebase from top to bottom. You follow one real path through it, such as a single request or button click, from entry point to database and back. Map what you find, ignore everything off that path for now, and repeat with a different path. Understanding builds in layers, and a first small change teaches more than a week of reading.
- QuestionDo I need Docker and Kubernetes as a junior developer?Docker, yes: learn the basics, because nearly every team uses containers and you will be expected to run the project locally and read a Dockerfile. Kubernetes, mostly no: understand what it does and a few core terms, but deep Kubernetes can wait until your job or a DevOps direction needs it.
- QuestionHow do I learn to write clean code as a junior developer?Clean code is a set of habits, not a book you finish. Fix names, function size, flag arguments and error handling one habit at a time, let a formatter and linter settle style, learn to refactor in small steps behind tests, and keep a list of the review comments you get twice: that list is your personal curriculum.
- QuestionWhat should I learn to become a web developer, and in what order?Learn the web platform first (HTML, CSS, JavaScript, how HTTP works), then one frontend framework, then a backend with a database, and build a real project at each stage. If you already know WordPress, you are not starting over: your HTML, CSS and PHP experience transfers.
- Resource· GuideSpring Boot Reference DocumentationThe official reference for Spring Boot: starters, auto-configuration, externalised configuration and profiles, data access, security, testing, packaging and Actuator. The place to find out what a property or starter really does in the release you are running.
- Resource· GuideSpring GuidesShort, task focused guides from the Spring team, each building one working thing: a REST service, data access with JPA, securing an app, messaging, caching, batch jobs, GraphQL, testing and more. Most take 15 to 30 minutes and start from Spring Initializr. They are the quickest way to see idiomatic Spring Boot code for a specific need, but they show how rather than why.
- Resource· GuideSpring Data JPA Reference DocumentationThe official reference for Spring Data JPA: repositories, query methods, @Query, projections, specifications, locking and transactions on top of JPA and Hibernate. Explains what your one-line repository methods really run against the database.
- Resource· GuideSpring Security Reference DocumentationThe official reference for Spring Security: the filter chain architecture, authentication, authorisation, OAuth2, CSRF and CORS protection, and testing. What you need to secure a Spring Boot API properly instead of switching protections off.
- Resource· GuideJUnit User GuideThe official user guide for JUnit, the standard unit testing framework for Java and the JVM. It explains how to write tests with JUnit Jupiter, use assertions and the test lifecycle, and set tests up in Maven, Gradle or your IDE. It suits Java students and new developers who want to test their core logic properly instead of checking output by hand.
Checked against 24 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Spring Initializr (start.spring.io)
- Spring Boot reference: Structuring your code
- Spring Boot reference: Externalized configuration
- Spring Boot reference: Testing Spring Boot applications
- Spring Boot reference: Testcontainers
- Spring Boot reference: Docker Compose support
- Spring Boot reference: Flyway migrations
- Spring Boot reference: Actuator endpoints and probes
- Spring Boot reference: Tracing with OpenTelemetry
- Spring Boot reference: Structured logging
- Spring Boot reference: Dockerfiles
- Spring Framework: Error responses (ProblemDetail)
- Spring Framework: HTTP service clients
- Spring Security: OAuth 2.0 resource server (JWT)
- Spring Security: CORS
- Spring Modulith reference
- springdoc-openapi
- MapStruct reference guide
- ArchUnit user guide
- Pact JVM: JUnit 5 provider
- Gatling: Maven plugin
- PIT mutation testing: quickstart for Maven
- OWASP dependency-check Maven plugin
- release-please
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Node.js API Best PracticesBuild Node.js REST APIs that hold up in production: structure, validation, error handling, security headers, rate limits, logging, testing and graceful shutdown.
- Observability Best PracticesKnow when production is hurting users and why: SLOs, golden signals, metric naming and cardinality, structured logs, OpenTelemetry traces and burn-rate alerts.
- PostgreSQL Best PracticesDesign, index, query and run PostgreSQL well: data types, constraints, EXPLAIN, zero-downtime migrations, pooling, transactions, backups and roles.
Checklists
See all- Database Migration ChecklistCheck a schema or data migration before it ships: expand and contract, lock behaviour, online indexes, batched backfills, rehearsal on real data, backups, rollback, deploy order and monitoring.
- Production Readiness ChecklistCheck a service before it takes real traffic: ownership, SLOs, capacity, timeouts and retries, alerts, rollout and rollback, backups, security and on-call.
- API Security ChecklistCheck your REST or GraphQL API against the OWASP API Security Top 10: authentication, object authorization, rate limits, input validation, SSRF, CORS and logging.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com