⚠️ Note: This project demonstrates fully functional, production-grade engineering practices, and is published for portfolio and educational purposes. While the codebase is complete and runnable, it is not intended for direct production use without additional security review, infrastructure improvements, and deployment hardening.
This codebase is curated and maintained by Uros, a backend engineer specializing in enterprise Java/Spring Boot solutions.
It demonstrates best practices in modern backend architecture, secure API design, and production-quality engineering.
This repository presents a complete, multi-tenant SaaS backend platform suitable for real-world business automation, team collaboration, and data management use cases.
It showcases how to architect, document, and secure a Java backend following the highest enterprise standards.
- 📊 REST API with Swagger/OpenAPI documentation
- 🔒 Custom JWT authentication & authorization
- 🛡️ Role-based and permission-based access control (RBAC & PBAC)
- 🚀 Modular, domain-driven design (DDD): clear separation into controller, service, repository, DTO, domain, and config layers
- 👥 User, Organization, Role, Permission, and AuditLog entities
- 📝 Audit/event logging with multi-tenant context
- 👤 User registration, password reset (with token flow), and soft deletion
- 📁 File upload/download: per-user & per-organization file storage
- 🔔 Real-time notifications via STOMP/WebSocket with secure JWT handshake
- 🌍 Advanced exception handling with full localization (i18n, multi-language support)
- ❤️ Health checks with custom Spring Boot Actuator indicators
- 🛡️ Fully integrated with Spring Security 6+
- 🧑💻 Sample data loader for demoing roles, permissions, and admin user
- 🐳 Docker-ready, intended for rapid onboarding and demo use
- Java 21+
- Spring Boot 3.5+
- Spring Security, Spring Data JPA
- MariaDB/MySQL
- Swagger / OpenAPI 3
- Lombok
- Maven (build tool)
- Docker (containerization support)
The project is easily adaptable to PostgreSQL and Gradle on request.
Below is the Entity-Relationship (ER) diagram illustrating the core database schema for this SaaS backend starter.
This schema is focused on the essential entities and relationships required for secure, multi-tenant SaaS business logic, while remaining fully extensible for real-world applications.
- Multi-tenant architecture: All user, file, and audit records are scoped per organization (tenant).
- Core entities:
User,Organization,Role,Permission, andAuditLog- Per-user and per-organization file management tables
- Relationships:
- Each user is linked to an organization.
- Flexible role & permission assignments enable fine-grained RBAC/PBAC.
- Audit/event logging tracks changes at user and organization level.
- Soft deletion is implemented via
deletedAtfields, ensuring a complete audit trail.
- Extensible foundation:
The model supports future business modules, custom fields, or new entities with minimal refactoring.
Note:
This schema is streamlined for the SaaS starter and contains fewer tables compared to large enterprise platforms, but follows the same best-practice architectural principles for clarity, scalability, and security.
- Solid lines represent strong foreign key relationships.
- Crow’s foot notation denotes cardinality (one-to-many, many-to-many).
- Key fields (
id) and audit columns (timestamps, soft delete) are marked for transparency.
For demo and portfolio purposes, this project is configured with:
spring.jpa.hibernate.ddl-auto=update
This enables automatic schema update on application startup.
⚠️ Production Usage Warning
- In any real production environment, database schema management must be handled via migration tools such as Flyway or Liquibase.
- The
ddl-autoproperty should be set tovalidate(ornone) to prevent accidental schema changes.- All credentials and secrets must be provided via secure mechanisms and never committed to version control.
This configuration is intentional, to simplify code review and enable easy local setup for demo purposes only.
Do not use this configuration in production.
This project is a fully runnable Spring Boot backend. You can clone the repository, build the app, and launch all services using Docker Compose.
Instructions:
- Start all services (build and run everything in Docker):
docker-compose up --build
- The backend API will be available at http://localhost:8080.
- Swagger UI: http://localhost:8080/swagger-ui/index.html
- MariaDB runs on port 3307 (container: 3306).
- Default admin user and demo data are loaded automatically on first run.
- Uploaded files are saved to the
uploads/directory (excluded from git). - All demo credentials and secrets are for local/testing only.
For production-grade deployment or additional integrations, contact me.
If you are on Linux or MacOS, you can use the included helper script to automate the build and startup process:
./run-demo.sh
Tip: If you get a "Permission denied" error, make the script executable:
chmod +x run-demo.sh
If you are on Windows, you can use the included helper script:
run-demo.cmdAll user-facing messages, errors, and API responses are fully localized.
The system comes with built-in support for English, Serbian, and German, and is easily extensible to any language by simply adding new message property files (e.g., messages_fr.properties).
- Dynamic locale detection based on user/browser preference or Accept-Language header.
- All validation errors, business exceptions, and success messages are localized.
- Extend or override messages without touching code.
See
src/main/resources/messages*.propertiesfor sample translations.
This repository is published strictly for portfolio and demonstration purposes.
- It is fully runnable locally for demo purposes, but it is not a production-ready deployment.
- This repository contains the entire backend codebase as used for local development, demo, and portfolio review. It is not intended as a ready-made production deployment, but as a comprehensive reference implementation.
- All secrets and credentials are intentionally omitted and should never be committed to version control.
All endpoints are fully documented using Swagger/OpenAPI.
Below are example screenshots from the live Swagger UI:
Complete API listing – all grouped endpoints at a glance.
Detailed export endpoint: file format selection, filtering, and response codes.
User login: required fields, request/response format, error handling.
Paged organizations list: pagination, filtering, and full response example.
- User Management endpoints overview
- Create User endpoint detail
- Role & Permission Management
- Audit Log querying
- Organization management
Example: User Authentication (Login)
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "admin@demo.com",
"password": "admin12345"
}Response:
{
"accessToken": "...",
"refreshToken": "...",
"tokenType": "Bearer"
}Example: Register New User
POST /api/v1/users/register
Content-Type: application/json
{
"email": "johndoe@example.com",
"password": "Secret123",
"fullName": "John Doe"
}src/
main/
java/
com/
urke/
saasbackendstarter/
audit/
config/
controller/
domain/
dto/
auth/
user/
organization/
role/
permission/
// Other DTOs (e.g., AuditLogDTO, NotificationMessage, etc.)
events/
exception/
health/
mapper/
repository/
security/
service/
impl/
resources/
messages.properties
messages_sr.properties
messages_de.properties
application.yaml
test/
java/
com/
urke/
saasbackendstarter/
// Unit and integration test classes
resources/
pom.xml
README.md
docker-compose.yml
Dockerfile
run-demo.sh
run-demo.cmd
mvnw
mvnw.cmd
.gitignore
This codebase follows industry best practices for testing and code quality.
- All key REST controllers (User, Role, Permission, Organization, Audit, Auth) are covered with dedicated unit tests using
@WebMvcTestand@MockBean. - Core service logic is tested for main business flows (e.g., user/role/organization management).
- Exception handling and validation edge cases are covered with controller and global handler tests.
- Audit logging and domain events are included in test scenarios.
- All tests are runnable out of the box (
mvn test), without any external setup. - The test directory structure mirrors the main package layout for clarity.
Full coverage reports (Jacoco) available on request or can be generated locally.
Example test output (all green):
mvn test
# ...
# Tests run: 10, Failures: 0, Errors: 0, Skipped: 0- Clean layering: Controller → Service → Repository, high cohesion and loose coupling.
- Modular design: DDD style, each concern isolated for maintainability.
- JWT Security: Stateless, with granular method-level access control (
@PreAuthorize). - Multi-tenancy: All user and audit data is scoped to organizations.
- Audit/Event System: All sensitive operations are tracked with org/user context.
- File Management: User/org file upload & download with security checks.
- i18n (Internationalization): All errors/messages localized via MessageSource and
messages.properties. - Centralized Exception Handling: Custom exceptions per domain, API-friendly error DTOs, and localization.
- Swagger/OpenAPI: Each controller method includes
@Operation,@ApiResponseannotations. - WebSocket (STOMP): Real-time notifications, secured by JWT handshake interceptor.
- Startup Data Loader: Demo roles, permissions, and admin user created at first run (in dev/demo profile).
- Health/Monitoring: Spring Boot Actuator endpoints + custom indicator for external API connectivity.
For technical deep-dive, architecture consultations, or backend contract work, contact via
LinkedIn.
This project is licensed under the MIT License. See the LICENSE file for details.
This is a personal portfolio project; external contributions are not being accepted at this time.
