# callme-ocean/spring-project-generator architecture

> Architecture diagram of the GitHub repository callme-ocean/spring-project-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/callme-ocean/spring-project-generator
- Repository: https://github.com/callme-ocean/spring-project-generator

## Overview

##### Project Type and Purpose
- This is a full-stack Spring Boot web application whose sole purpose is to generate a complete, best-practice Spring microservice scaffold on demand and serve it as a downloadable ZIP.
- The README confirms it exposes a web UI (Thymeleaf) and a REST API endpoint (`/api/spring-project-generator/v1/generator`), accepts user parameters (project name, group, packages, API types, Java version), invokes a set of shell scripts, and returns a ZIP.

##### File Structure
- Top-level artifacts:
- Dockerfile (containerization)
- pom.xml (Maven build with Spring Boot parent)
- src/main/java/in/oceanbytes/spring_project_generator (Java packages)
- src/main/resources/scripts/*.sh (shell scripts for scaffolding)
- src/main/resources/static (CSS/JS assets)
- src/main/resources/templates/index.html (Thymeleaf UI)
- application.yml (runtime configuration)
- Java sub-packages follow an MVC & layered-architecture pattern:
- controllers: HTTP endpoints & UI controller
- services: business logic orchestration of script invocation
- aspects: AOP logging
- exceptions: domain exceptions & global handler
- models: data transfer objects (ProjectRequest)
- utils: script/file helper classes

##### Key Insights from the README
- Workflow overview: User ↔ UI/REST → Controller → Service → ScriptUtils/FileUtils → Shell scripts → Filesystem → ZIP → HTTP response
- Modular shell scripts each handle one domain (directories, classes, configs)
- Thymeleaf + static assets for the web UI
- No external DB; ephemeral filesystem operations and ZIP streaming

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        UI["Thymeleaf UI<br/>index.html"]:::frontend
        CSS["Static CSS<br/>styles.css"]:::frontend
        JS["Static JS<br/>script.js"]:::frontend
    end

    %% Infrastructure Boundary
    subgraph "Docker Container" 
        direction TB

        %% Spring Boot Application
        subgraph "Spring Boot Application" 
            direction TB
            Controller["Controller Layer<br/>HomeController"]:::mvc
            Service["Service Layer<br/>ProjectService"]:::mvc
            AOP["AOP Logging Aspect<br/>LoggingAspect"]:::aspect
            ExceptionHandler["Global Exception Handler<br/>GlobalExceptionHandler"]:::exception
            ErrorDTO["Error Details DTO<br/>ErrorDetails"]:::exception
            ServiceEx["Service Exception<br/>ServiceException"]:::exception
            Model["Data Model<br/>ProjectRequest"]:::mvc
            FileUtils["File Utilities<br/>FileUtils"]:::util
            ScriptUtils["Script Utilities<br/>ScriptUtils"]:::util
            Config["Configuration<br/>application.yml"]:::config
        end

        %% Shell Scripts & Filesystem
        subgraph "Scaffolding Engine & Filesystem"
            direction TB
            Scripts["Shell Scripts"]:::script
            FS["Filesystem / ZIP Generator"]:::fs
        end

    end

    %% Interactions
    UI -->|"GET /"| Controller
    CSS --> UI
    JS --> UI

    UI -->|"POST /api/spring-project-generator/v1/generator"| Controller
    Controller -->|"invoke generateProject()"| Service
    Controller -.->|"intercept"| AOP
    Service -->|"throws ServiceException"| ServiceEx
    ServiceEx -->|"handled by"| ExceptionHandler
    ExceptionHandler -->|"returns ErrorDetails JSON"| UI

    Service -->|"call ScriptUtils"| ScriptUtils
    Service -->|"call FileUtils"| FileUtils
    ScriptUtils -->|"exec scripts"| Scripts
    FileUtils --> FS
    Scripts --> FS
    FS -->|"stream ZIP"| Controller
    Controller -->|"HTTP Response (ZIP)"| UI

    Config -.->|"injection"| Service
    Config -.->|"injection"| ScriptUtils

    %% Click Events
    click UI "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/resources/templates/index.html"
    click CSS "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/resources/static/css/styles.css"
    click JS "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/resources/static/js/script.js"
    click Controller "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/controllers/HomeController.java"
    click Service "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/services/ProjectService.java"
    click AOP "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/aspects/LoggingAspect.java"
    click ExceptionHandler "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/exceptions/GlobalExceptionHandler.java"
    click ErrorDTO "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/exceptions/ErrorDetails.java"
    click ServiceEx "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/exceptions/ServiceException.java"
    click Model "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/models/ProjectRequest.java"
    click FileUtils "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/utils/FileUtils.java"
    click ScriptUtils "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/java/in/oceanbytes/spring_project_generator/utils/ScriptUtils.java"
    click Config "https://github.com/callme-ocean/spring-project-generator/blob/main/src/main/resources/application.yml"
    click Scripts "https://github.com/callme-ocean/spring-project-generator/tree/main/src/main/resources/scripts"
    %% individual scripts directory click to directory

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef mvc fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef aspect fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef exception fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px;
    classDef util fill:#e2e3e5,stroke:#383d41,color:#383d41,stroke-width:1px;
    classDef config fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-width:1px;
    classDef script fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef fs fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
```
