Water Framework
"Empty your mind, be formless. Shapeless, like water... Be water, my friend." – Bruce Lee
Build Enterprise Java in Minutes, Not Months
The first cross-framework Java library that combines Yeoman generators, Claude Code AI assistance, and proven enterprise patterns to achieve unprecedented development velocity.
From Zero to Microservice in 3 Commands
The yo water generator + Claude Code turns hours of boilerplate into seconds of scaffolding.
Scaffold your project
yo water:newProject \
--inline \
--projectName MyService \
--applicationType service \
--runtime springGenerates a complete Spring Boot project with DDD structure, build configuration, and OSGi/Spring descriptors.
Add your entity
yo water:entity \
--inline \
--entityName Product \
--entityPackage com.myapp.productCreates entity class, repository, service, REST controller, and Karate integration tests — all wired together.
Build and run
yo water:build \
--projects MyServiceCompiles, runs tests (80%+ coverage enforced), generates the Water descriptor, and publishes artifacts.
Claude Code + Water = Extreme Productivity
Water Framework is designed from the ground up to be AI-assisted. Every module follows consistent patterns, every concept is well-defined, and the yo water generator speaks the same language as your AI pair programmer.
- Consistent patterns — Claude understands Water conventions immediately
- Generator-first — AI can scaffold entire microservices in one command
- CLAUDE.md per module — deep context for accurate code generation
- Test generation — AI writes Karate REST + JUnit tests at 80%+ coverage
- Service mesh wiring — AI manages waterDescriptor PINs automatically
// Generated by Claude Code in seconds:
@FrameworkComponent
@AccessControl(
availableActions = {CrudActions.class},
rolesPermissions = {
@DefaultRoleAccess(
roleName = "productManager",
actions = {CrudActions.class})
}
)
@Entity
@Table(name = "product")
public class Product extends AbstractJpaEntity
implements ProtectedEntity {
@NotNull @NoMalitiusCode
private String name;
@NotNull
private double price;
private String description;
}Architectural Pillars
DDD & Microservices
Domain-Driven Design with bounded contexts, aggregates, and microservices patterns. Every entity, service, and REST controller follows the same structure — forever learnable by AI.
Framework-Agnostic Core
Write your domain logic once, deploy on Spring Boot, Apache Karaf (OSGi), or Quarkus. The same codebase, any runtime — no lock-in.
Enterprise Security
RBAC with fine-grained permissions using @AllowPermissions, @AllowGenericPermissions, and @AllowRoles. Security is declarative, not imperative.
Service Mesh & Discovery
Built-in API Gateway, Service Discovery, and integration clients. Declare input/output PINs in waterDescriptor and the framework wires your service mesh automatically.
JPA Repository Pattern
Fluent QueryBuilder, pagination, optimistic locking, and entity extensions. One repository interface, backed by Hibernate, with full transaction management.
REST API Framework
JAX-RS and Spring MVC dual support with automatic Swagger documentation, JWT security filters, and standardized error handling out of the box.
Component Lifecycle
Lightweight IoC with @FrameworkComponent, @Inject, @OnActivate/@OnDeactivate. Works identically across OSGi, Spring, and Quarkus.
AOP Interceptors
Cross-cutting concerns — security, validation, transactions — handled by a chain of interceptors. Write clean business code without infrastructure noise.
Service Mesh Wiring — Automatic & Declarative
Declare what your service provides and what it needs. Water wires the rest.
waterDescriptor {
moduleId = 'com.myapp.product'
displayName = 'Product Service'
output {
// This service exposes the product API
pin('com.myapp.integration.product') {}
}
input {
// Needs JDBC and Service Discovery
standardPin 'jdbc'
standardPin 'service-discovery'
// Needs permission checks from Permission service
pin('it.water.integration.permission') {}
}
}Output PINs
Declare what integration contracts your module exposes to the rest of the platform.
Input PINs
Declare what external services your module depends on. Standard PINs: jdbc, service-discovery, authentication-issuer, api-gateway.
Descriptor Graph
The generateWaterDescriptor task produces water-descriptor.json — a machine-readable service contract used by the platform to wire your mesh.
In-Process or Remote
Integration clients work identically whether the target service runs in the same JVM or as a remote REST microservice. Switch without changing a line of business code.
Visual Microservice Designer
Design your entire microservice architecture by drawing it. Drag & drop modules, connect PINs visually, and auto-generate waterDescriptor blocks — no manual configuration required. Combined with Claude Code, describe your architecture in natural language and export a ready-to-build workspace.
Out-of-the-Box Modules
Production-ready modules covering security, integration, connectors, and infrastructure — all following the same Water patterns.
Identity & Access Management
User Management
Complete user lifecycle: registration, activation, password reset, BCrypt hashing, and role assignment. REST-ready with UserManager cross-service integration.
Authentication
JWT-based authentication with pluggable AuthenticationProvider strategy. Supports multiple issuers and token refresh flows.
Role & Permission System
Fine-grained RBAC with bitmask action encoding, entity-level and instance-level permissions. The @AccessControl annotation wires everything declaratively.
Shared Entity
Grant other users access to your owned entities. The SharedEntity marker interface plus the SHARE action permission — that's all it takes.
Service Mesh & Infrastructure
API Gateway
Reverse proxy with dynamic route management, circuit breaker, rate limiting, and load balancing. REST-configurable with full CRUD on routes and rate-limit rules.
View moduleService Discovery
In-memory service registry for dynamic service resolution across the Water mesh. Every REST-exposing service registers automatically via the service-discovery input PIN.
Company / Multi-Tenancy
Multi-tenant resource management with company-scoped ownership, member management, and per-company access policies. Includes OwnedResource support.
Email Service
Pluggable email provider with FreeMarker template support. Used for activation emails, password resets, and custom notification flows.
View moduleConnectors & Integrations
Kafka Connector
Event streaming integration with Apache Kafka for asynchronous message processing and event-driven architectures.
View moduleEthereum Connector
Blockchain integration for Ethereum-compatible networks. Manage network configs and smart contracts as JPA entities via the EthClient abstraction.
Storage S3
AWS S3-compatible object storage integration for document management, file uploads, and binary asset handling.
View moduleDocuments Manager
Document lifecycle management with versioning, metadata, and pluggable storage backend. Integrates with Storage S3 out of the box.
View moduleOne Codebase. Any Runtime.
Write your domain logic once. Water's runtime abstraction handles the rest.
Spring Boot
Full Spring ecosystem integration with auto-configuration, Spring Security, and Spring Data JPA. Deploy as a standard Spring Boot application.
Spring IntegrationOSGi / Karaf
Dynamic module system with true hot-deploy, fine-grained classloading, and enterprise OSGi container support via Apache Karaf.
OSGi IntegrationQuarkus
Native compilation with GraalVM, fast startup, and low memory footprint. Ideal for cloud-native and serverless deployments.
Quarkus IntegrationCore Concepts
Component Registry
Central registry for managing and discovering components. Provides lifecycle hooks, dependency injection, and cross-cutting interceptor chains.
Learn moreSecurity Context
Unified security model across runtimes. The Runtime object provides the current SecurityContext — who's logged in, their roles, and their entity ID.
Permission System
Declarative RBAC via @AccessControl, @AllowPermissions, and @DefaultRoleAccess. Permission interceptors enforce access at service boundaries.
Repository Pattern
Fluent QueryBuilder, pagination with PaginatedResult, optimistic locking, and entity extensions — all abstracted from the underlying JPA provider.