Skip to main content

🗂️ Project Structure Overview

This document provides an overview of the Springular project structure, explaining the organization of directories, key packages, and architectural decisions. It helps developers understand the codebase layout and navigate the project efficiently.

Top-Level Directories​

  • .github - Contains workflow files responsible for CI/CD pipeline.

  • client - Angular frontend application.

  • server - Spring Boot backend application.

    • src/main/java/com/saas/springular: Main application code, following a Hybrid package structure:
      • common: Shared utilities and logic.
        • stripe: Everything related to Stripe integration is encapsulated in this folder. Classes here are package-private, ensuring better encapsulation and easier maintenance.
          • stripe directory is a good example of why you should use a hybrid package structure instead of a package-per-layer approach:
            • Centralized Logic: All Stripe-related code (models, services, controllers, etc.) is located in one place, making it easy to navigate and understand.
            • Encapsulation: Every single class in this directory is package-private, reducing unnecessary exposure.
            • Easier Feature Extensions: When adding or modifying functionality, you don't need to jump between multiple packages (e.g., service, controller, repository). This minimizes cognitive load and speeds up development.
            • Improved Code Organization: Domain logic isn't scattered across layers, making the application structure more intuitive and maintainable.
      • user: Domain-specific logic for user management.
      • <new packages for each domain/feature, not by layer>
      • src/main/resources:
        • db/migration: Flyway migration scripts in SQL format.
        • templates/emails: Email templates (can use Thymeleaf HTML or SendGrid templates).
        • application.yml: The main configuration file for the backend application.

  • docs - Documentation powered by Docusaurus.

    • docs: Markdown files for the documentation.
    • docusaurus.config.js: Configuration for Docusaurus.

Important Files​

  • docker-compose.yml - Defines the infrastructure of the entire project. This file is used for deploying Springular to a VPS using Coolify.

  • docker-compose-test.yml - Test version of docker-compose.yml being used in CI/CD workflow.
    Reminder: Update this file whenever changes are made to docker-compose.yml.

  • .env - Stores all environment variables.
    You can initialize the base .env file using the following command:

    cp .env.example .env