Update README.md to enhance service description, features, and usage …

README.md

@@ -1,27 +1,32 @@
 # Methodologist Setup Service
 
-A Spring Boot REST API service for validating and standardizing GenModel files for MWE2 workflow compatibility.
+A Spring Boot REST API service for the Vitruv methodologist workflow. It validates and standardizes
+GenModel files for MWE2 compatibility, and generates ready-to-build VSUM projects from uploaded
+metamodel, genmodel, and reaction files.
 
 ## Features
 
-- **GenModel Validation**: Inspect GenModel files for compliance issues
-- **GenModel Processing**: Automatically apply standardization rules to GenModel files
-- **REST API**: Clean and intuitive RESTful endpoints
-- **Error Handling**: Comprehensive error reporting and validation
-- **Docker Support**: Ready-to-use Docker setup
+- **GenModel Validation**: Inspect GenModel files for compliance issues without modifying them
+- **GenModel Processing**: Apply standardization rules and download the corrected file
+- **VSUM Project Generation**: Build a complete VSUM project from metamodels, genmodels, and
+  reactions, returned as a zip archive
+- **VSUM Jar Build**: Build the project and return only the executable jar-with-dependencies
+- **OpenAPI / Swagger UI**: Interactive API documentation
+- **Error Handling**: Centralized exception handling with structured error responses
+- **Docker Support**: Dockerfile and Compose setup included
 
 ## Quick Start
 
 ### Prerequisites
 
 - Java 21+
-- Maven 3.8+
+- Maven 3.8+ (or the bundled `./mvnw` wrapper)
 - Docker (optional)
 
 ### Build
 
 ```bash
-mvn clean package
+./mvnw clean package
 ```
 
 ### Run Locally
@@ -30,21 +35,28 @@ mvn clean package
 java -jar target/methodologist-setup-service-0.0.1-SNAPSHOT.jar
 ```
 
-The service will start on `http://localhost:8090`
+The service starts on `http://localhost:8090`.
 
 ### Run with Docker
 
+The `Dockerfile` copies the jar from the build context root, and `target/` is excluded via
+`.dockerignore`, so the jar must be staged first:
+
 ```bash
+./mvnw clean package
+cp target/methodologist-setup-service-0.0.1-SNAPSHOT.jar .
 docker compose up --build
 ```
 
 ## API Endpoints
 
+Interactive docs: `http://localhost:8090/swagger-ui.html` — OpenAPI spec: `http://localhost:8090/api-docs`
+
 ### Inspect GenModel
 
-**POST** `/api/genmodel/inspect`
+**POST** `/api/genmodel/inspect` (`multipart/form-data`)
 
-Analyzes a GenModel file and **previews** what changes would be applied.
+Analyzes a GenModel file and **previews** what changes would be applied. Returns JSON.
 
 ```bash
 curl -X POST -F "file=@mymodel.genmodel" http://localhost:8090/api/genmodel/inspect
@@ -54,45 +66,75 @@ Response:
 
 ```json
 {
-  "status": "success",
-  "message": "GenModel inspected successfully, showing planned changes",
-  "issues": [
+  "data": [
     {
       "filename": "mymodel.genmodel",
       "message": "Would remove attributes: complianceLevel"
     }
-  ]
+  ],
+  "message": "GenModel inspected successfully, showing planned changes"
 }
 ```
 
 ### Process GenModel
 
-**POST** `/api/genmodel/process`
+**POST** `/api/genmodel/process` (`multipart/form-data`)
 
-Analyzes a GenModel file and **applies** the standardization changes.
+Applies the standardization rules and returns the **processed file itself** as a download
+(`application/octet-stream`), not a JSON summary.
 
 ```bash
-curl -X POST -F "file=@mymodel.genmodel" http://localhost:8090/api/genmodel/process
+curl -X POST -F "file=@mymodel.genmodel" \
+  -o mymodel.processed.genmodel \
+  http://localhost:8090/api/genmodel/process
 ```
 
-Response:
+### Build VSUM Project
 
-```json
-{
-  "status": "success",
-  "message": "GenModel processed and changes applied successfully",
-  "issues": [
-    {
-      "filename": "mymodel.genmodel",
-      "message": "Removed attributes: complianceLevel"
-    }
-  ]
-}
+**POST** `/api/vsum/build` (`multipart/form-data`)
+
+Uploads metamodel, genmodel, and reaction files, generates the project from FreeMarker templates,
+builds it, and returns the whole project as a zip archive (`vsum-project-<timestamp>.zip`).
+
+Parts:
+
+| Part | Required | Description |
+| --- | --- | --- |
+| `metamodelFiles` | yes | One or more `.ecore` metamodel files |
+| `genmodelFiles` | yes | `.genmodel` files, paired **by index** with `metamodelFiles` |
+| `reactionFiles` | yes | One or more `.reactions` files |
+
+`metamodelFiles` and `genmodelFiles` must have the same count — index *n* of one is matched with
+index *n* of the other. Reaction imports are normalized against the uploaded metamodels' nsURIs.
+
+```bash
+curl -X POST \
+  -F "metamodelFiles=@model.ecore" \
+  -F "genmodelFiles=@model.genmodel" \
+  -F "reactionFiles=@example.reactions" \
+  -o vsum-project.zip \
+  http://localhost:8090/api/vsum/build
+```
+
+### Build VSUM Jar
+
+**POST** `/api/vsum/jar` (`multipart/form-data`)
+
+Same inputs and pairing rules as `/api/vsum/build`, but returns only the executable
+jar-with-dependencies produced under `vsum/target` (`application/java-archive`).
+
+```bash
+curl -X POST \
+  -F "metamodelFiles=@model.ecore" \
+  -F "genmodelFiles=@model.genmodel" \
+  -F "reactionFiles=@example.reactions" \
+  -o vsum.jar \
+  http://localhost:8090/api/vsum/jar
 ```
 
 ## Standardization Rules
 
-The service automatically applies these normalization rules:
+The GenModel endpoints apply these normalization rules:
 
 1. **Removes deprecated attributes:**
     - `complianceLevel`, `compliance`, `editDirectory`, `editorDirectory`, etc.
@@ -113,11 +155,22 @@ The service automatically applies these normalization rules:
 
 ```
 src/main/java/tools/vitruv/methodologist/setup/
-├── api/
-│   ├── controller/        # REST controllers
-│   └── dto/               # Data Transfer Objects
-├── service/               # Business logic layer
+├── model/
+│   ├── controller/           # GenModel REST controller + DTOs
+│   └── service/              # GenModel precheck and file services
+├── vsum/
+│   ├── controller/           # VSUM REST controller
+│   └── service/              # Project generation, templating, and build
+├── config/                   # Swagger, Vitruv config, exception handling, class loading
+├── emf/                      # EMF model initialization
+├── exception/                # Custom exceptions and error DTOs
+├── log/                      # Request/response logging filter
+├── messages/                 # Error and info message constants
+├── util/                     # File helpers
+├── ResponseTemplateDto.java  # Generic API response envelope
 └── MethodologistSetupServiceApplication.java
+
+src/main/resources/templates/ # FreeMarker templates for generated VSUM projects
 ```
 
 ## Health Check
@@ -128,24 +181,36 @@ curl http://localhost:8090/actuator/health
 
 ## Configuration
 
-See `src/main/resources/application.properties` for available configurations.
+See `src/main/resources/application.properties`.
 
 Default settings:
 
 - Port: `8090`
-- Application Name: `methodologist-setup-service`
+- Application name: `methodologist-setup-service`
+- Swagger UI: `/swagger-ui.html`
+- OpenAPI docs: `/api-docs`
+- Log level for `tools.vitruv.methodologist`: `DEBUG`
 
 ## Technologies
 
 - **Framework**: Spring Boot 4.0.6
-- **Modeling**: Eclipse EMF (EMF Ecore, EMF GenModel, EMF Codegen)
-- **XML Processing**: StAX (Streaming API for XML)
-- **Build Tool**: Maven 3.8+
+- **Modeling**: Eclipse EMF 2.35.0 (Ecore, XMI, Codegen)
+- **Templating**: FreeMarker
+- **API Docs**: springdoc-openapi 3.0.0
+- **Logging**: Logback with logstash JSON encoder
+- **Build Tool**: Maven (Spotless, Checkstyle, Surefire)
 - **Java Version**: 21 LTS
 
-## Documentation
+## Development
+
+```bash
+./mvnw clean verify        # full build with tests
+./mvnw spotless:apply      # auto-format sources
+./mvnw checkstyle:check    # style check against checkstyle.xml
+```
 
-For detailed API documentation, see [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
+CI (`.github/workflows/ci.yml`) runs `mvnw clean verify` on PRs to `main` and `develop`, plus
+nightly SonarQube analysis and a Checkstyle review pass.
 
 ## Error Handling
 
@@ -155,4 +220,5 @@ All requests return appropriate HTTP status codes:
 - `400 Bad Request`: Invalid input or processing error
 - `500 Internal Server Error`: Unexpected server error
 
-Error responses include detailed messages to help with debugging.
+Errors are handled centrally in `GlobalExceptionHandler` and returned as structured responses with
+a message and error code to help with debugging.