{"id":51745469,"url":"https://github.com/urosengineer/saas-backend-starter","last_synced_at":"2026-07-18T18:13:50.985Z","repository":{"id":368614014,"uuid":"1001431183","full_name":"urosengineer/saas-backend-starter","owner":"urosengineer","description":"Java/Spring Boot SaaS backend starter with multi-tenancy, auth, access control, audit logging and file management.","archived":false,"fork":false,"pushed_at":"2026-07-01T11:04:30.000Z","size":475,"stargazers_count":11,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-01T12:25:13.091Z","etag":null,"topics":["backend","ddd","docker","enterprise","file-upload","i18n","java","jwt","pbac","portfolio","rbac","rest-api","saas","security","spring-boot","swagger","websocket"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urosengineer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-13T11:17:16.000Z","updated_at":"2026-07-01T11:03:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/urosengineer/saas-backend-starter","commit_stats":null,"previous_names":["urosengineer/saas-backend-starter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/urosengineer/saas-backend-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Fsaas-backend-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Fsaas-backend-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Fsaas-backend-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Fsaas-backend-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urosengineer","download_url":"https://codeload.github.com/urosengineer/saas-backend-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urosengineer%2Fsaas-backend-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35626580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","ddd","docker","enterprise","file-upload","i18n","java","jwt","pbac","portfolio","rbac","rest-api","saas","security","spring-boot","swagger","websocket"],"created_at":"2026-07-18T18:13:50.237Z","updated_at":"2026-07-18T18:13:50.974Z","avatar_url":"https://github.com/urosengineer.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# saas-backend-starter\n\n[![CI](https://github.com/urosengineer/saas-backend-starter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/urosengineer/saas-backend-starter/actions/workflows/ci.yml)\n\n\u003e **Status:** Portfolio reference project. Feature-complete snapshot maintained for dependency/security compatibility, CI health, and documentation accuracy.\n\u003e\n\u003e ⚠️ **Note:** This project demonstrates a complete, runnable backend reference implementation and is published for portfolio and educational purposes.\n\u003e While the codebase is complete and runnable, it is not intended for direct production use without additional security review, infrastructure improvements, and deployment hardening.\n\nThis codebase is curated and maintained by Uros, a backend engineer specializing in enterprise Java/Spring Boot solutions.  \nIt demonstrates practical patterns in modern backend architecture, secure API design, and maintainable Spring Boot engineering.\n\nThis repository presents a **complete, multi-tenant SaaS backend reference implementation** for common business backend concerns such as authentication, authorization, tenant-scoped data, auditing, file handling, and API documentation.\nIt showcases how to structure, document, and secure a Java backend using enterprise-style Spring Boot practices.\n\n---\n\n## Features\n\n- 📊 **REST API** with [Swagger/OpenAPI](#api-documentation) documentation  \n- 🔒 **Custom JWT authentication \u0026 authorization**  \n- 🛡️ **Role-based and permission-based access control** (RBAC \u0026 PBAC)  \n- 🚀 **Modular, domain-driven design** (DDD): clear separation into controller, service, repository, DTO, domain, and config layers  \n- 👥 **User, Organization, Role, Permission, and AuditLog entities**  \n- 📝 **Audit/event logging** with multi-tenant context  \n- 👤 **User registration, password reset (with token flow), and soft deletion**  \n- 📁 **File upload/download**: per-user \u0026 per-organization file storage  \n- 🔔 **Real-time notifications** via **STOMP/WebSocket** with secure JWT handshake  \n- 🌍 **Advanced exception handling** with full localization (i18n, multi-language support)  \n- ❤️ **Health checks** with custom [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html) indicators  \n- 🛡️ **Fully integrated with Spring Security 6+**  \n- 🧑‍💻 **Sample data loader** for demoing roles, permissions, and admin user  \n- 🐳 **Docker-ready**, intended for rapid onboarding and demo use\n\n---\n\n## Technologies\n\n- **Java 21+**\n- **Spring Boot 3.5+**\n- **Spring Security, Spring Data JPA**\n- **MariaDB/MySQL**\n- **Swagger / OpenAPI 3**\n- **Lombok**\n- **Maven** (build tool)\n- **Docker** (containerization support)\n\n\u003e The project is easily adaptable to PostgreSQL and Gradle on request.\n\n---\n\n## Database Entity-Relationship (ER) Diagram\n\nBelow is the Entity-Relationship (ER) diagram illustrating the **core database schema** for this SaaS backend starter.  \nThis 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.\n\n![Database ER Diagram](docs/saas_backend_schema.png)\n\n### Diagram Overview\n\n- **Multi-tenant architecture**: All user, file, and audit records are scoped per organization (tenant).\n- **Core entities**:  \n  - `User`, `Organization`, `Role`, `Permission`, and `AuditLog`\n  - Per-user and per-organization file management tables\n- **Relationships**:\n  - Each user is linked to an organization.\n  - Flexible role \u0026 permission assignments enable fine-grained RBAC/PBAC.\n  - Audit/event logging tracks changes at user and organization level.\n  - Soft deletion is implemented via `deletedAt` fields, ensuring a complete audit trail.\n- **Extensible foundation**:  \n  The model supports future business modules, custom fields, or new entities with minimal refactoring.\n\n\u003e **Note:**  \n\u003e 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.\n\n### Reading the Diagram\n\n- **Solid lines** represent strong foreign key relationships.\n- **Crow’s foot notation** denotes cardinality (one-to-many, many-to-many).\n- **Key fields** (`id`) and audit columns (timestamps, soft delete) are marked for transparency.\n\n---\n\n## Database Schema Auto-Update\n\nFor demo and portfolio purposes, this project is configured with:\n\n    spring.jpa.hibernate.ddl-auto=update\n\nThis enables automatic schema update on application startup.\n\n\u003e ⚠️ **Production Usage Warning**  \n\u003e\n\u003e - In any real production environment, database schema management **must** be handled via migration tools such as [Flyway](https://flywaydb.org/) or [Liquibase](https://www.liquibase.org/).\n\u003e - The `ddl-auto` property should be set to `validate` (or `none`) to prevent accidental schema changes.\n\u003e - All credentials and secrets **must** be provided via secure mechanisms and **never committed to version control**.\n\u003e\n\u003e This configuration is **intentional**, to simplify code review and enable easy local setup for demo purposes only.\n\u003e\n\u003e **Do not use this configuration in production.**\n\n---\n\n## 🟢 Runnable Demo – Quick Start\n\nThis project is a fully runnable Spring Boot backend.\nYou can clone the repository, build the app, and launch all services using Docker Compose.\n\n**Instructions:**\n\n1. **Start all services (build and run everything in Docker):**\n    ```bash\n    docker-compose up --build\n    ```\n\n- The backend API will be available at [http://localhost:8080](http://localhost:8080).\n- **Swagger UI:** [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html)\n- MariaDB runs on port **3307** (container: 3306).\n- Default admin user and demo data are loaded automatically on first run.\n- Uploaded files are saved to the `uploads/` directory (excluded from git).\n- All demo credentials and secrets are for **local/testing only**.\n\n\u003e For production-grade deployment or additional integrations, contact me.\n\n---\n\n## Helper Script (Linux / MacOS)\n\nIf you are on Linux or MacOS, you can use the included helper script to automate the build and startup process:\n\n```\n./run-demo.sh\n```\n\nTip: If you get a \"Permission denied\" error, make the script executable:\n\n```\nchmod +x run-demo.sh\n```\n\n---\n\n## Windows users\n\nIf you are on Windows, you can use the included helper script:\n\n```cmd\nrun-demo.cmd\n```\n\n---\n\n## Internationalization (i18n) Support\n\nAll user-facing messages, errors, and API responses are fully localized.  \nThe 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`).\n\n- **Dynamic locale detection** based on user/browser preference or Accept-Language header.\n- All validation errors, business exceptions, and success messages are localized.\n- Extend or override messages without touching code.\n\n\u003e See `src/main/resources/messages*.properties` for sample translations.\n\n---\n\n## ⚠️ Portfolio / Demo Notice\n\nThis repository is published strictly for portfolio and demonstration purposes.  \n\n- It is fully runnable locally for demo purposes, but it is not a production-ready deployment.\n- 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.\n- All secrets and credentials are intentionally omitted and should never be committed to version control.\n\n---\n\n## API Documentation\n\nAll endpoints are fully documented using Swagger/OpenAPI.  \nBelow are example screenshots from the live Swagger UI:\n\n### Swagger UI Screenshots\n\n![API Overview](docs/swagger-overview.png)\n*Complete API listing – all grouped endpoints at a glance.*\n\n![Export Users Endpoint](docs/swagger-user-export-detail.png)\n*Detailed export endpoint: file format selection, filtering, and response codes.*\n\n![Login Endpoint Detail](docs/swagger-auth-login-detail.png)\n*User login: required fields, request/response format, error handling.*\n\n![Organizations Endpoint Detail](docs/swagger-orgs-list-detail.png)\n*Paged organizations list: pagination, filtering, and full response example.*\n\n\n- User Management endpoints overview\n- Create User endpoint detail\n- Role \u0026 Permission Management\n- Audit Log querying\n- Organization management\n\n---\n\n**Example: User Authentication (Login)**\n```http\nPOST /api/v1/auth/login\nContent-Type: application/json\n\n{\n  \"email\": \"admin@demo.com\",\n  \"password\": \"admin12345\"\n}\n```\n\n**Response:**\n```json\n{\n  \"accessToken\": \"...\",\n  \"refreshToken\": \"...\",\n  \"tokenType\": \"Bearer\"\n}\n```\n\n**Example: Register New User**\n```http\nPOST /api/v1/users/register\nContent-Type: application/json\n\n{\n  \"email\": \"johndoe@example.com\",\n  \"password\": \"Secret123\",\n  \"fullName\": \"John Doe\"\n}\n```\n## Project Structure\n\n```\nsrc/\n    main/\n        java/\n            com/\n                urke/\n                    saasbackendstarter/\n                        audit/\n                        config/\n                        controller/\n                        domain/\n                        dto/\n                            auth/\n                            user/\n                            organization/\n                            role/\n                            permission/\n                            // Other DTOs (e.g., AuditLogDTO, NotificationMessage, etc.)\n                        events/\n                        exception/\n                        health/\n                        mapper/\n                        repository/\n                        security/\n                        service/\n                            impl/\n        resources/\n            messages.properties\n            messages_sr.properties\n            messages_de.properties\n            application.yaml\n    test/\n        java/\n            com/\n                urke/\n                    saasbackendstarter/\n                        // Unit and integration test classes\n        resources/\npom.xml\nREADME.md\nCHANGELOG.md\ndocker-compose.yml\nDockerfile\nrun-demo.sh\nrun-demo.cmd\nmvnw\nmvnw.cmd\n.github/workflows/ci.yml\n.gitignore\n```\n\n---\n\n## Test Coverage\n\nThis codebase follows industry best practices for testing and code quality.\n\n- All key REST controllers (User, Role, Permission, Organization, Audit, Auth) are covered with dedicated unit tests using `@WebMvcTest` and `@MockBean`.\n- Core service logic is tested for main business flows (e.g., user/role/organization management).\n- Exception handling and validation edge cases are covered with controller and global handler tests.\n- Audit logging and domain events are included in test scenarios.\n- All tests are runnable out of the box (`./mvnw -B test`), without any external setup.\n- The test directory structure mirrors the main package layout for clarity.\n\n\u003e Full coverage reports (Jacoco) available on request or can be generated locally.\n\nExample test output (all green):\n\n```bash\n./mvnw -B test\n# ...\n# Tests run: 45, Failures: 0, Errors: 0, Skipped: 0\n```\n\n## Continuous Integration\n\nThe repository includes a GitHub Actions CI workflow that runs on pushes and pull requests to `master`.\n\n- Builds with Java 21.\n- Caches Maven dependencies.\n- Runs the full Maven test suite with `./mvnw -B test`.\n- Verifies the application package with `./mvnw -B package -DskipTests`.\n\n---\n\n## Key Architecture Highlights\n\n- **Clean layering:** Controller → Service → Repository, high cohesion and loose coupling.\n- **Modular design:** DDD style, each concern isolated for maintainability.\n- **JWT Security:** Stateless, with granular method-level access control (`@PreAuthorize`).\n- **Multi-tenancy:** All user and audit data is scoped to organizations.\n- **Audit/Event System:** All sensitive operations are tracked with org/user context.\n- **File Management:** User/org file upload \u0026 download with security checks.\n- **i18n (Internationalization):** All errors/messages localized via MessageSource and `messages.properties`.\n- **Centralized Exception Handling:** Custom exceptions per domain, API-friendly error DTOs, and localization.\n- **Swagger/OpenAPI:** Each controller method includes `@Operation`, `@ApiResponse` annotations.\n- **WebSocket (STOMP):** Real-time notifications, secured by JWT handshake interceptor.\n- **Startup Data Loader:** Demo roles, permissions, and admin user created at first run (in dev/demo profile).\n- **Health/Monitoring:** Spring Boot Actuator endpoints + custom indicator for external API connectivity.\n\n---\n\n## Portfolio \u0026 Contact\n\nFor technical deep-dive, architecture consultations, or backend contract work, contact via  \n[LinkedIn](https://www.linkedin.com/in/uros-ilic-6a201436a/).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n## Contribution\n\nThis is a personal portfolio project; **external contributions are not being accepted** at this time.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furosengineer%2Fsaas-backend-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furosengineer%2Fsaas-backend-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furosengineer%2Fsaas-backend-starter/lists"}