feat: Update documentation for multi-module architecture and improve encapsulation

- Update README.md with comprehensive documentation for new API/SDK separation
- Add clear installation instructions for both API-only and complete SDK usage
- Document architecture benefits and module responsibilities
- Update provider and hook development sections to reference API module
- Make DefaultOpenFeatureAPI package-private with package-private constructor

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
Signed-off-by: Simon  Schrottner <[email protected]>

Author: aepfli

README.md

@@ -52,7 +52,11 @@ Note that this library is intended to be used in server-side contexts and has no
 
 ### Install
 
-#### Maven
+OpenFeature Java is now structured as a multi-module project with separate API and SDK artifacts. In most cases, you'll want to use the full SDK, but you can also use just the API if you're building a provider or need a lighter dependency.
+
+#### Complete SDK (Recommended)
+
+For full OpenFeature functionality, use the SDK module:
 
 <!-- x-release-please-start-version -->
 ```xml
@@ -64,6 +68,20 @@ Note that this library is intended to be used in server-side contexts and has no
 ```
 <!-- x-release-please-end-version -->
 
+#### API Only
+
+For provider development or minimal dependencies, use the API module:
+
+<!-- x-release-please-start-version -->
+```xml
+<dependency>
+    <groupId>dev.openfeature</groupId>
+    <artifactId>api</artifactId>
+    <version>1.16.0</version>
+</dependency>
+```
+<!-- x-release-please-end-version -->
+
 If you would like snapshot builds, this is the relevant repository information:
 
 ```xml
@@ -81,6 +99,7 @@ If you would like snapshot builds, this is the relevant repository information:
 
 #### Gradle
 
+Complete SDK:
 <!-- x-release-please-start-version -->
 ```groovy
 dependencies {
@@ -89,6 +108,15 @@ dependencies {
 ```
 <!-- x-release-please-end-version -->
 
+API only:
+<!-- x-release-please-start-version -->
+```groovy
+dependencies {
+    implementation 'dev.openfeature:api:1.16.0'
+}
+```
+<!-- x-release-please-end-version -->
+
 ### Usage
 
 ```java
@@ -123,6 +151,19 @@ public void example(){
 
 See [here](https://javadoc.io/doc/dev.openfeature/sdk/latest/) for the Javadocs.
 
+## 🏗️ Architecture
+
+OpenFeature Java SDK is structured as a multi-module project:
+
+- **`openfeature-api`**: Core interfaces, data types, and contracts. Use this if you're building providers or hooks, or if you need minimal dependencies.
+- **`openfeature-sdk`**: Full implementation with all OpenFeature functionality. This is what most applications should use.
+
+This separation allows for:
+- **Cleaner dependencies**: Provider and hook developers only need the lightweight API module
+- **Better modularity**: Clear separation between contracts (API) and implementation (SDK)  
+- **Easier testing**: Components can be tested against the API contracts
+- **Reduced coupling**: Implementation details are isolated in the SDK module
+
 ## 🌟 Features
 
 | Status | Features                                                            | Description                                                                                                                                                   |
@@ -327,9 +368,17 @@ Additionally, you can develop a custom transaction context propagator by impleme
 
 ### Develop a provider
 
-To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
+To develop a provider, you need to create a new project and include the OpenFeature API as a dependency (you only need the API module for provider development).
 This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/java-sdk-contrib) available under the OpenFeature organization.
-You’ll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.
+You'll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature API.
+
+```xml
+<dependency>
+    <groupId>dev.openfeature</groupId>
+    <artifactId>api</artifactId>
+    <version>1.16.0</version>
+</dependency>
+```
 
 ```java
 public class MyProvider implements FeatureProvider {
@@ -413,10 +462,18 @@ OpenFeatureAPI.getInstance().getClient().getProviderState();
 
 ### Develop a hook
 
-To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.
+To develop a hook, you need to create a new project and include the OpenFeature API as a dependency (you only need the API module for hook development).
 This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/java-sdk-contrib) available under the OpenFeature organization.
 Implement your own hook by conforming to the `Hook interface`.
 
+```xml
+<dependency>
+    <groupId>dev.openfeature</groupId>
+    <artifactId>api</artifactId>
+    <version>1.16.0</version>
+</dependency>
+```
+
 ```java
 class MyHook implements Hook {
 

openfeature-sdk/src/main/java/dev/openfeature/sdk/DefaultOpenFeatureAPI.java

@@ -31,9 +31,10 @@
  * Default implementation of OpenFeature API that provides full SDK functionality.
  * This implementation extends the abstract API and provides all OpenFeature capabilities including
  * provider management, event handling, transaction context management, and lifecycle management.
+ * Package-private - users should access this through OpenFeatureAPI.getInstance().
  */
 @SuppressWarnings("PMD.UnusedLocalVariable")
-public class DefaultOpenFeatureAPI extends OpenFeatureAPI {
+class DefaultOpenFeatureAPI extends OpenFeatureAPI {
     private static final Logger log = LoggerFactory.getLogger(DefaultOpenFeatureAPI.class);
     // package-private multi-read/single-write lock
     static AutoCloseableReentrantReadWriteLock lock = new AutoCloseableReentrantReadWriteLock();
@@ -47,8 +48,9 @@ public class DefaultOpenFeatureAPI extends OpenFeatureAPI {
      * Creates a new DefaultOpenFeatureAPI instance with default settings.
      * Initializes the API with empty hooks, a provider repository, event support,
      * and a no-op transaction context propagator.
+     * Package-private constructor - this class should only be instantiated by the SDK.
      */
-    public DefaultOpenFeatureAPI() {
+    DefaultOpenFeatureAPI() {
         apiHooks = new ConcurrentLinkedQueue<>();
         providerRepository = new ProviderRepository(this);
         eventSupport = new EventSupport();
@@ -435,7 +437,8 @@ void addHandler(String domain, ProviderEvent event, Consumer<EventDetails> handl
                     .orElse(ProviderState.READY)
                     .matchesEvent(event)) {
                 eventSupport.runHandler(
-                        handler, dev.openfeature.api.EventDetails.eventDetailsBuilder().domain(domain).build());
+                        handler,
+                        EventDetails.eventDetailsBuilder().domain(domain).build());
             }
             eventSupport.addClientHandler(domain, event, handler);
         }