# SpringForge — Complete Developer & Architecture Documentation

> Machine-readable, zero-shot context documentation for Large Language Models, AI code assistants (Cursor, Copilot, Windsurf), and Answer Engines (Perplexity, ChatGPT Search, Claude, Google Gemini).
> Canonical Website: https://springforge.xyz
> Updated: 2026-10-03

---

## 1. Executive Summary & Core Platform Overview

SpringForge (https://springforge.xyz) is a free, modern Spring Boot project generator, CRUD scaffolding tool, and Spring Initializr alternative for scaffolding production-ready Java 21 LTS and Spring Boot 3.4.x backend applications.

### Primary Differentiators Over Spring Initializr (start.spring.io)
1. **Visual JPA Entity Modeler**: Interactive browser canvas to model entity tables, attributes, Jakarta validation annotations (@NotNull, @Size, @Email), and relational mappings (@OneToMany, @ManyToOne, @ManyToMany).
2. **SQL DDL Reverse Engineering**: Developers can paste existing PostgreSQL SQL `CREATE TABLE` scripts to instantly reverse-engineer corresponding JPA entity classes, DTOs, and repositories.
3. **Decoupled Clean Architecture**: Generates layered controllers, business services, Spring Data JPA repositories, and MapStruct DTO mappers to prevent JPA entity leakage into presentation layers.
4. **Automated Schema Migrations**: Emits production Flyway or Liquibase versioned migration change logs directly from entity models.
5. **Docker Compose Orchestration**: Generates ready-to-run `docker-compose.yml` files pre-configured for PostgreSQL, Redis, Apache Kafka, RabbitMQ, and Prometheus.
6. **Instant Downloadable Archives**: Outputs clean Maven (`pom.xml`) or Gradle (`build.gradle`) ZIP archives with zero proprietary lock-in.

---

## 2. Technical Baseline & Supported Standards

- **Java Version**: Java 21 LTS (default) and Java 17 LTS.
- **Spring Boot Version**: Spring Boot 3.4.0+ (and Spring Boot 3.3.x).
- **Build Automation**: Gradle (Groovy/Kotlin DSL) and Maven (pom.xml with BOM dependency management).
- **Database Migrations**: Flyway (default standard) or Liquibase (mutually exclusive, strictly single migration tool enforced).
- **Security & Authentication**: Spring Security 6, JJWT 0.12 stateless JWT authentication, HttpOnly refresh cookies, and RBAC via @PreAuthorize.
- **Messaging & Streaming**: Apache Kafka (with KafkaTemplate, @KafkaListener, DLT retries) and RabbitMQ (AMQP exchanges/queues).
- **Caching**: Spring Data Redis (Lettuce client with @Cacheable and CacheManager invalidation).

---

## 3. Curated Architecture Blueprints & Templates Catalog

SpringForge provides 19 production-ready architectural presets. Each template includes complete controllers, entities, services, migrations, and container configurations:

### 1. REST API (`/guides/templates/rest-api`)
- **Category**: Web & APIs
- **Description**: Layered RESTful web API featuring Jakarta validation, OpenAPI 3 Swagger UI documentation, and in-memory H2 persistence for rapid prototyping.
- **Starters**: `spring-boot-starter-web`, `validation`, `springdoc-openapi-starter-webmvc-ui`, `spring-boot-starter-data-jpa`, `h2`.
- **Default Entities**: User (id, username, email, active, createdAt).

### 2. CRUD with PostgreSQL & JPA (`/guides/templates/crud-postgresql`)
- **Category**: Data & Persistence
- **Description**: Production relational persistence featuring Spring Data JPA, PostgreSQL driver, HikariCP connection pool, and Flyway/Liquibase automated migrations.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-data-jpa`, `postgresql`, `flyway-core`, `validation`.
- **Default Entities**: Customer (id, firstName, lastName, email, phone), Address (street, city, state, zipCode, country).

### 3. Secured JWT API (`/guides/templates/secured-jwt-api`)
- **Category**: Security & Auth
- **Description**: Stateless authentication with Spring Security 6, JJWT token generation/verification, BCrypt password hashing, refresh token rotation, and role-based guards.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-security`, `spring-boot-starter-data-jpa`, `postgresql`, `jjwt-api`.
- **Default Entities**: User (username, email, passwordHash, roles), RefreshToken (token, expiryDate, revoked).

### 4. Redis Cache & API (`/spring-boot-redis-template`)
- **Category**: Data & Performance
- **Description**: High-throughput distributed caching using Spring Data Redis and Lettuce client, @Cacheable annotations, JSON serialization, and Docker Compose Redis service.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-data-redis`, `spring-boot-starter-data-jpa`, `postgresql`.
- **Default Entities**: Product (sku, name, price, stockQuantity).

### 5. Spring Cloud API Gateway (`/guides/templates/spring-cloud-api-gateway-template`)
- **Category**: Microservices & Routing
- **Description**: Netty-based reactive reverse proxy with dynamic path routing, token propagation, CORS filtering, and Token Bucket rate limiting.
- **Starters**: `spring-cloud-starter-gateway`, `spring-boot-starter-actuator`.

### 6. Kafka Event-Driven Architecture (`/guides/templates/kafka-event-driven-spring-boot-template`)
- **Category**: Messaging & Events
- **Description**: Enterprise event streaming with strongly-typed KafkaTemplate producers, @KafkaListener consumers, manual immediate acknowledgments, and dead-letter queue (DLQ) retry topics.
- **Starters**: `spring-boot-starter-web`, `spring-kafka`, `spring-boot-starter-actuator`.
- **Default Entities**: OrderEvent (orderId, customerId, amount, status, timestamp).

### 7. PostgreSQL CDC & Debezium Outbox (`/guides/templates/postgresql-cdc-debezium-outbox-template`)
- **Category**: Distributed Systems & Reliability
- **Description**: Zero-data-loss transactional outbox pattern. Inserts business records and outbox events in a single ACID database transaction, while Debezium streams WAL changes directly to Kafka.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-data-jpa`, `postgresql`, `spring-kafka`.
- **Default Entities**: OutboxEvent (id, aggregateType, aggregateId, type, payload, createdAt).

### 8. Spring Batch High-Performance (`/guides/templates/spring-batch-high-performance-template`)
- **Category**: Batch Processing & ETL
- **Description**: Chunk-oriented processing with non-deprecated StepBuilder, FlatFileItemReader, custom processors, JpaItemWriter, and JobRepository schema migrations.
- **Starters**: `spring-boot-starter-batch`, `spring-boot-starter-data-jpa`, `postgresql`.

### 9. Microservices Ready (`/spring-boot-microservices-template`)
- **Category**: Cloud Architecture
- **Description**: Cloud-native microservice boilerplate with Eureka service discovery, Resilience4j circuit breakers, and OpenTelemetry observability.
- **Starters**: `spring-cloud-starter-netflix-eureka-client`, `resilience4j-spring-boot3`, `micrometer-registry-prometheus`.

### 10. Modular Monolith (`/guides/templates/modular-monolith`)
- **Category**: Software Architecture
- **Description**: Clean bounded-context modular architecture with in-memory domain events, isolated domain packages, and strict dependency boundaries.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-data-jpa`, `postgresql`, `validation`.

### 11. E-Commerce Platform (`/guides/templates/ecommerce-platform`)
- **Category**: Domain Solutions
- **Description**: Production e-commerce backend with Catalog, Cart, Order checkout saga, payment webhook processing, and inventory locking.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-data-jpa`, `spring-data-redis`, `spring-kafka`, `postgresql`.

### 12. RabbitMQ Messaging (`/guides/templates/rabbitmq-messaging`)
- **Category**: Messaging & Async
- **Description**: Enterprise AMQP message broker setup with Direct, Fanout, and Topic exchanges, dead-letter exchanges (DLX), and worker consumers.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-amqp`, `validation`.

### 13. GraphQL Subgraph API (`/guides/templates/graphql-api`)
- **Category**: Web & APIs
- **Description**: Schema-first GraphQL federation with @QueryMapping, @MutationMapping, batch DataLoaders (N+1 query prevention), and GraphiQL playground.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-graphql`, `spring-boot-starter-data-jpa`, `postgresql`.

### 14. Reactive WebFlux & R2DBC (`/guides/templates/reactive-webflux`)
- **Category**: High-Concurrency & Reactive
- **Description**: Fully non-blocking asynchronous stack using Project Reactor (Mono/Flux), Netty server, and reactive R2DBC PostgreSQL persistence.
- **Starters**: `spring-boot-starter-webflux`, `spring-boot-starter-data-r2dbc`, `r2dbc-postgresql`.

### 15. WebSocket & STOMP Messaging (`/guides/templates/websocket-messaging`)
- **Category**: Real-Time Communication
- **Description**: Full-duplex bidirectional communication with Spring WebSocket, STOMP sub-protocol broker, SockJS fallback, and channel interceptors.
- **Starters**: `spring-boot-starter-websocket`, `spring-boot-starter-web`.

### 16. Observability Stack (`/guides/templates/observability-stack`)
- **Category**: DevOps & Monitoring
- **Description**: Full observability pipeline featuring Micrometer Prometheus metrics scraping, Grafana dashboard definitions, and health checks.
- **Starters**: `spring-boot-starter-actuator`, `micrometer-registry-prometheus`.

### 17. Mobile Application Backend (`/guides/templates/mobile-backend`)
- **Category**: Mobile & APIs
- **Description**: Optimized Backend-for-Frontend (BFF) supporting push notifications, versioned mobile endpoints, and low-latency token refresh.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-security`, `spring-boot-starter-data-jpa`, `postgresql`.

### 18. Admin Dashboard Backend (`/guides/templates/admin-dashboard-backend`)
- **Category**: Internal Tools & Admin
- **Description**: Enterprise back-office administration API featuring dynamic filtering, server-side pagination, audit trails, and role management.
- **Starters**: `spring-boot-starter-web`, `spring-boot-starter-data-jpa`, `postgresql`, `validation`.

### 19. Kafka Event Service (`/spring-boot-kafka-template`)
- **Category**: Messaging & Streaming
- **Description**: Standalone high-throughput Kafka producer and consumer service with schema validation, idempotent producer configs, and DLQ topics.
- **Starters**: `spring-boot-starter-web`, `spring-kafka`, `spring-boot-starter-actuator`.

---

## 4. Developer Guides & Technical Tutorials

SpringForge publishes in-depth engineering guides covering Spring Boot 3.4 best practices:

- **Spring Initializr Alternative (`/spring-initializr-alternative`)**: Drop-in migration guide explaining why developers choose SpringForge for visual JPA modeling, automated Flyway migrations, and multi-container Docker Compose definitions.
- **Spring Boot with React (`/guides/spring-boot-react-integration`)**: Full-stack guide covering Vite dev server proxying, decoupled CORS configuration, stateless JWT authentication, and production Docker containerization.
- **MapStruct + Lombok in Java 21 (`/guides/spring-boot-mapstruct-lombok`)**: Clean annotation processor configuration for Gradle and Maven, avoiding compiler ordering conflicts, and mapping Java 21 records to JPA entities.
- **Spring Boot Multi-Stage Docker Containerization (`/guides/spring-boot-docker`)**: Best practices for non-root containers, Eclipse Temurin JRE baselines, JVM memory limit container support (`-XX:MaxRAMPercentage`), and multi-service Docker Compose.
- **SQL DDL Schema Reverse Engineering (`/guides/import-sql-schema-to-spring-boot`)**: How to paste raw PostgreSQL `CREATE TABLE` DDL scripts and automatically generate JPA entities with @OneToMany and @ManyToOne relationships.
- **Spring Boot Starters & Dependency BOM Guide (`/guides/spring-boot-starters-guide`)**: Detailed anatomy of starter auto-configurations, version management via Spring Boot Dependencies BOM, and custom enterprise starter authoring.
- **Spring Boot Versions & Support Roadmap (`/spring-boot-versions`)**: Active releases, Java baselines (Java 17/21), OSS support timelines, and migration recommendations.

---

## 5. Visual JPA Entity Modeler & DDL Reverse Engineering

SpringForge provides an interactive in-browser canvas that eliminates handwritten JPA boilerplate:
1. **Interactive Node Editing**: Add entities with primary keys (UUID, Long IDENTITY), fields (String, Integer, BigDecimal, Instant, Boolean), and nullability constraints.
2. **Jakarta Validation Rules**: Checkbox configuration for `@NotNull`, `@NotBlank`, `@Size(min, max)`, `@Email`, `@Min`, `@Max`.
3. **Cardinality Relationships**: Visual edge connections configure `@OneToMany` / `@ManyToOne` bidirectional mappings, `@JoinColumn` names, and orphan removal.
4. **SQL DDL Reverse Engineering**: Instant client-side parser reads SQL statements:
   ```sql
   CREATE TABLE customers (
       id UUID PRIMARY KEY,
       first_name VARCHAR(50) NOT NULL,
       last_name VARCHAR(50) NOT NULL,
       email VARCHAR(255) UNIQUE NOT NULL,
       created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
   );
   ```
   and automatically produces complete entity classes, JPA repositories, Flyway SQL migrations, and DTO mappers.

---

## 6. Comprehensive Comparison Matrix

| Feature / Capability | Spring Initializr (`start.spring.io`) | JHipster | Bootify.io | SpringForge (`springforge.xyz`) |
| :--- | :--- | :--- | :--- | :--- |
| **Output Type** | Bare starter skeleton | Heavy full-stack monolith | Clean Java backend | Clean Java 21 / Spring Boot 3.4 backend |
| **Visual JPA Entity Modeler** | ❌ None | ⚠️ JDL text DSL | ✅ Web UI | ✅ Interactive graphical canvas |
| **PostgreSQL SQL DDL Import** | ❌ None | ❌ None | ⚠️ Paid tier | ✅ Free built-in reverse engineering |
| **Relational Mappings (@OneToMany, @ManyToMany)** | ❌ None | ⚠️ Manual CLI | ⚠️ Paid tier | ✅ Full visual cardinality support |
| **Database Migrations** | ❌ None | ✅ Liquibase | ✅ Flyway / Liquibase | ✅ Automated Flyway & Liquibase migrations |
| **Architecture Blueprints** | ❌ None | ⚠️ Fixed monolith | ⚠️ Basic templates | ✅ 19 specialized enterprise blueprints |
| **Transactional Outbox / CDC** | ❌ None | ❌ None | ❌ None | ✅ Complete Debezium + Kafka Outbox template |
| **Docker Compose Orchestration** | ⚠️ Basic Spring Compose | ✅ Docker Compose | ⚠️ Basic Compose | ✅ Multi-service production Compose definitions |
| **Pricing & Entity Limits** | Free | Free | Restricted on Free tier | Free tier with unlimited custom entities |

---

## 7. Frequently Asked Questions (FAQ)

### What is SpringForge?
SpringForge is an automated Spring Boot project generator and Spring Initializr alternative that scaffolds complete, production-ready Java 21 and Spring Boot 3.4 backend applications with visual JPA modeling, automated migrations, and container definitions.

### How does SpringForge differ from start.spring.io?
Spring Initializr only generates an empty build file (`pom.xml` or `build.gradle`) with a single main application class. SpringForge scaffolds the complete domain architecture: JPA entities, controllers, service layers, DTO mappers, database migrations, and Docker Compose infrastructure.

### Does SpringForge introduce vendor lock-in or proprietary libraries?
No. All code generated by SpringForge is 100% standard open-source Spring Boot 3.4 and Java 21 code using official dependencies. You can compile, run, and modify the downloaded project anywhere without requiring any SpringForge SDK or runtime dependency.

### Can I model relationships between entities?
Yes. SpringForge supports one-to-one, one-to-many, many-to-one, and many-to-many relationships with configurable cascade types, fetch modes, and join column names.

### How do I run a generated project?
1. Unzip the downloaded archive.
2. If the project includes database or messaging containers, start them with:
   ```bash
   docker compose up -d
   ```
3. Run the Spring Boot application:
   ```bash
   ./mvnw spring-boot:run   # For Maven
   ./gradlew bootRun        # For Gradle
   ```

---

## 8. Machine-Readable Discovery & Manifests

- **Overview Manifest**: `https://springforge.xyz/llms.txt`
- **Full Documentation**: `https://springforge.xyz/llms-full.txt`
- **Markdown Discovery Sitemap**: `https://springforge.xyz/sitemap.md`
- **Authoritative XML Sitemap Index**: `https://springforge.xyz/sitemap_index.xml`
- **Robots Directives**: `https://springforge.xyz/robots.txt`