sirius-framework-mcp 0.1.0

package/dist/resources/biz/codelists.md

@@ -0,0 +1,154 @@
+# Code Lists and Lookup Tables
+
+Code lists and lookup tables provide managed enumerations for master data. They map
+codes to human-readable names and additional metadata, with support for
+internationalization and multiple data sources.
+
+## CodeList — The Classic Approach
+
+`CodeList` is the original database-backed enumeration. It follows the entity triple
+pattern with `CodeListData` as the shared composite:
+
+```java
+public interface CodeList extends TenantAware, Traced {
+    Mapping CODE_LIST_DATA = Mapping.named("codeListData");
+    CodeListData getCodeListData();
+}
+```
+
+Implementations: `SQLCodeList` (JDBC) and `MongoCodeList` (MongoDB). Each code list
+belongs to a tenant and contains `CodeListEntry` items (code + value + description).
+
+### CodeLists Service
+
+```java
+@Part
+private CodeLists codeLists;
+
+// Look up a value
+String countryName = codeLists.getValue("countries", "DE").orElse("Unknown");
+
+// Check if a code exists
+boolean valid = codeLists.hasValue("countries", "DE");
+```
+
+## LookupTable — The Modern Approach
+
+`LookupTable` is an abstraction layer over multiple data sources. A lookup table can
+be backed by:
+
+- **CodeList** — tenant-specific data from the database (`CodeListLookupTable`)
+- **Jupiter IDB tables** — high-performance Redis-like key-value store (`IDBLookupTable`)
+- **Config files** — static data from HOCON configuration (`ConfigLookupTable`)
+- **Custom implementations** — via `CustomLookupTable`
+
+The data source is selected via configuration:
+
+```hocon
+lookup-tables {
+    countries {
+        type = "code-list"    # or "idb", "config", "custom"
+        codeList = "countries"
+    }
+    currencies {
+        type = "idb"
+        table = "currencies"
+    }
+}
+```
+
+### Key Operations
+
+```java
+@Part
+private LookupTables lookupTables;
+
+LookupTable table = lookupTables.fetchTable("countries");
+
+// Normalize a code (resolve aliases)
+Optional<String> code = table.normalize("DEU");  // -> "DE"
+
+// Resolve a display name
+Optional<String> name = table.resolveName("DE");  // -> "Germany"
+
+// Fetch additional fields
+Optional<String> iso3 = table.fetchField("DE", "iso3");
+
+// Search/suggest
+List<LookupTableEntry> matches = table.suggest("Germ", new Limit(0, 10));
+```
+
+## LookupValue — Entity Field Type
+
+`LookupValue` is a field type for embedding a lookup table reference directly in
+an entity. It replaces raw string fields with a typed, validated reference:
+
+```java
+private final LookupValue salutation = new LookupValue(
+        "salutations",                        // lookup table name
+        LookupValue.Display.NAME,             // show name in UI
+        LookupValue.Display.CODE_AND_NAME,    // extended display
+        LookupValue.Export.CODE,              // export the code
+        LookupValue.CustomValues.REJECT       // reject unknown values
+);
+```
+
+### Display and Export Modes
+
+**Display** controls what users see in the UI:
+- `Display.CODE` — show the raw code (e.g., "DE")
+- `Display.NAME` — show the resolved name (e.g., "Germany")
+- `Display.CODE_AND_NAME` — show both (e.g., "Germany (DE)")
+
+**Export** controls what appears in CSV/Excel exports:
+- `Export.CODE` — export the raw code
+- `Export.NAME` — export the resolved name
+
+**CustomValues** controls validation:
+- `CustomValues.ACCEPT` — allow values not in the lookup table
+- `CustomValues.REJECT` — reject unknown values with a validation error
+
+The framework uses `LookupValue` internally, e.g., `PersonData.salutation` is a
+`LookupValue` backed by the `"salutations"` table.
+
+## LookupValues — Multi-Value Field
+
+`LookupValues` stores multiple codes from the same lookup table as a list:
+
+```java
+private final LookupValues tags = new LookupValues("product-tags");
+```
+
+## CustomLookupTable
+
+For data sources that do not fit the built-in types, implement `CustomLookupTable`:
+
+```java
+@Register
+public class MyCustomTable extends CustomLookupTable {
+    @Override
+    public String getName() { return "my-table"; }
+
+    @Override
+    public Optional<String> normalize(String code) { ... }
+
+    @Override
+    public Optional<String> resolveName(String code, String language) { ... }
+}
+```
+
+## Common Mistakes
+
+1. **Using raw strings instead of `LookupValue`** — Storing a code as a plain
+   `String` field loses validation, display formatting, and autocomplete support.
+
+2. **Wrong `CustomValues` mode** — Using `REJECT` on a table where users need to
+   enter free-form values causes validation failures. Use `ACCEPT` when the table
+   is advisory rather than authoritative.
+
+3. **Confusing CodeList and LookupTable** — `CodeList` is the raw database entity.
+   `LookupTable` is the abstraction layer. Always program against `LookupTable`
+   unless you need direct CRUD on the code list entries.
+
+4. **Missing lookup table configuration** — A `LookupValue` referencing a table
+   name that has no configuration in `lookup-tables { }` will fail at runtime.

package/dist/resources/biz/entity-triple.md

@@ -0,0 +1,142 @@
+# Entity Triple Pattern
+
+The entity triple is the standard pattern for database-portable entities in sirius-biz.
+Every entity exists as three artifacts: an interface, a JDBC implementation, and a
+MongoDB implementation. This lets application code program against the interface while
+the framework routes persistence to whichever database is active.
+
+## Step 1 — Interface (Base Package)
+
+Define the interface in the main package (e.g., `sirius.biz.tenants`). It extends
+`Entity` plus any mixins and declares `Mapping` constants and accessor methods:
+
+```java
+@SuppressWarnings("squid:S1214")
+@Explain("We rather keep the constants here, as this emulates the behaviour and layout of a real entity.")
+public interface Tenant<I extends Serializable>
+        extends Entity, Transformable, Traced, Journaled, RateLimitedEntity, PerformanceFlagged {
+
+    String PERMISSION_SYSTEM_TENANT = "flag-system-tenant";
+
+    Mapping PARENT = Mapping.named("parent");
+    Mapping TENANT_DATA = Mapping.named("tenantData");
+
+    BaseEntityRef<I, ? extends Tenant<I>> getParent();
+    TenantData getTenantData();
+    boolean hasPermission(String permission);
+}
+```
+
+Key rules:
+- Use `@Explain` to justify constants in the interface (SonarQube rule S1214).
+- Parameterize with `<I extends Serializable>` for the database ID type.
+- Keep all field data in a `Composite` (e.g., `TenantData`) so that both
+  implementations share the same field definitions.
+
+## Step 2 — JDBC Implementation (`jdbc/` Subpackage)
+
+Place the SQL entity in a `jdbc/` subpackage. It extends `BizEntity` (which gives
+you `TraceData`) or `SQLTenantAware` (if tenant-scoped) and implements the interface:
+
+```java
+@Framework(SQLTenants.FRAMEWORK_TENANTS_JDBC)
+@TranslationSource(Tenant.class)
+public class SQLTenant extends BizEntity implements Tenant<Long> {
+
+    @Autoloaded
+    @AutoImport
+    @NullAllowed
+    private final SQLEntityRef<SQLTenant> parent =
+            SQLEntityRef.on(SQLTenant.class, SQLEntityRef.OnDelete.SET_NULL);
+
+    public static final Mapping TENANT_DATA = Mapping.named("tenantData");
+    private final TenantData tenantData = new TenantData(this);
+
+    private final SQLPerformanceData performanceData = new SQLPerformanceData(this);
+
+    // ... implement interface methods
+}
+```
+
+Key annotations:
+- **`@Framework("biz.tenants-jdbc")`** — gates this entity behind a framework flag.
+  Only loaded when `sirius.frameworks { biz.tenants-jdbc = true }` is set.
+- **`@TranslationSource(Tenant.class)`** — tells the i18n system to look up property
+  labels from the interface, not this class. Without this, you need duplicate `.properties`.
+- Use `SQLEntityRef<T>` for references to other SQL entities.
+- The ID type is `Long` (auto-increment).
+
+## Step 3 — MongoDB Implementation (`mongo/` Subpackage)
+
+Place the Mongo entity in a `mongo/` subpackage. It extends `MongoBizEntity` (which
+gives `TraceData` and prefix search) or `MongoTenantAware` (if tenant-scoped):
+
+```java
+@Framework(MongoTenants.FRAMEWORK_TENANTS_MONGO)
+@TranslationSource(Tenant.class)
+public class MongoTenant extends MongoBizEntity implements Tenant<String> {
+
+    @Autoloaded
+    @NullAllowed
+    private final MongoRef<MongoTenant> parent =
+            MongoRef.on(MongoTenant.class, MongoRef.OnDelete.SET_NULL);
+
+    public static final Mapping TENANT_DATA = Mapping.named("tenantData");
+    private final TenantData tenantData = new TenantData(this);
+
+    private final MongoPerformanceData performanceData = new MongoPerformanceData(this);
+
+    // ... implement interface methods
+}
+```
+
+Key differences from SQL:
+- Use `MongoRef<T>` instead of `SQLEntityRef<T>`.
+- The ID type is `String` (MongoDB ObjectId).
+- `MongoBizEntity` extends `PrefixSearchableEntity` for built-in text search.
+
+## Base Class Selection
+
+| Scenario                        | JDBC Base Class    | Mongo Base Class     |
+|---------------------------------|--------------------|----------------------|
+| Standalone entity               | `BizEntity`        | `MongoBizEntity`     |
+| Tenant-scoped entity            | `SQLTenantAware`   | `MongoTenantAware`   |
+| No tracing needed (rare)        | `SQLEntity`        | `MongoEntity`        |
+
+## @Framework vs @Register(framework = ...)
+
+This distinction is critical and a frequent source of bugs:
+
+- **`@Framework`** — used on **entity classes**. Controls whether the entity is
+  registered in the schema and ORM. Without it, the entity loads unconditionally.
+- **`@Register(framework = "...")`** — used on **services, controllers, and other
+  components**. Controls whether the class participates in dependency injection.
+
+```java
+// Entity — use @Framework
+@Framework("biz.tenants-jdbc")
+public class SQLTenant extends BizEntity { ... }
+
+// Service — use @Register(framework = ...)
+@Register(classes = Processes.class, framework = "biz.processes")
+public class Processes { ... }
+```
+
+## Common Mistakes
+
+1. **Wrong base class** — Using `SQLEntity` instead of `BizEntity` loses `TraceData`.
+   Using `BizEntity` for a tenant-scoped entity misses the automatic tenant reference.
+
+2. **Missing `@Framework`** — The entity loads in all configurations and creates
+   database tables even when the feature is disabled.
+
+3. **Missing `@TranslationSource`** — Property labels defined for the interface
+   (e.g., `Tenant.tenantData.name`) are not found by the SQL/Mongo implementation.
+   You end up with raw property names in the UI.
+
+4. **Forgetting the Composite** — Putting fields directly in both implementations
+   instead of using a shared `Composite` leads to drift and duplication.
+
+5. **ID type mismatch** — JDBC entities use `Long`, Mongo entities use `String`.
+   The interface must be parameterized with `<I extends Serializable>` to abstract
+   over this difference.

package/dist/resources/biz/importer.md

@@ -0,0 +1,153 @@
+# Importer Framework
+
+The import framework provides a structured way to import data into entities from
+external sources (CSV, Excel, XML, JSON). It handles field mapping, entity lookup,
+create-or-update logic, batch operations, and extensibility through events.
+
+## Import Handler Hierarchy
+
+Every entity type that can be imported needs an `ImportHandler`. The hierarchy:
+
+- `BaseImportHandler<E>` — abstract base with convenience methods
+  - `SQLEntityImportHandler<E>` — for JDBC/SQL entities, uses batch queries
+  - `MongoEntityImportHandler<E>` — for MongoDB entities
+
+Create a handler by extending the appropriate base class:
+
+```java
+@Register(classes = ImportHandler.class, framework = "biz.tenants-jdbc")
+public class SQLTenantImportHandler extends SQLEntityImportHandler<SQLTenant> {
+
+    @Override
+    protected Class<SQLTenant> getType() {
+        return SQLTenant.class;
+    }
+
+    @Override
+    protected void collectFindQueries(
+            Consumer<Tuple<Predicate<SQLTenant>, Supplier<FindQuery<SQLTenant>>>> queryConsumer) {
+        queryConsumer.accept(Tuple.create(
+                tenant -> Strings.isFilled(tenant.getTenantData().getAccountNumber()),
+                () -> insertQuery.newFindQuery()
+                        .where(SQLTenant.TENANT_DATA.inner(TenantData.ACCOUNT_NUMBER))
+        ));
+    }
+}
+```
+
+## @AutoImport Annotation
+
+Mark entity fields with `@AutoImport` to include them in automatic import mapping.
+When `BaseImportHandler.getAutoImportMappings()` is called, all `@AutoImport` fields
+are collected and can be mapped from import columns:
+
+```java
+@AutoImport
+@Length(150)
+@Trim
+private String name;
+
+@AutoImport
+@NullAllowed
+private String accountNumber;
+```
+
+This works together with the `ImportDictionary` which maps column headers to entity
+properties.
+
+## Event System
+
+The importer fires events at each stage of the import lifecycle. Register handlers
+to customize behavior:
+
+| Event                       | When Fired                                    |
+|-----------------------------|-----------------------------------------------|
+| `BeforeLoadEvent`           | Before populating entity fields from input    |
+| `AfterLoadEvent`            | After populating fields, before find/match    |
+| `BeforeFindEvent`           | Before attempting to find an existing entity  |
+| `BeforeCreateOrUpdateEvent` | Before persisting (create or update)          |
+| `AfterCreateOrUpdateEvent`  | After entity is persisted                     |
+| `BeforeDeleteEvent`         | Before deleting an entity                     |
+
+Events are dispatched to `EntityImportHandlerExtender` implementations, which are
+collected via `@Parts(EntityImportHandlerExtender.class)` and can hook into any
+stage of the import lifecycle.
+
+## Find Queries — Matching Existing Records
+
+`collectFindQueries()` defines how the importer matches incoming data to existing
+entities. Each query is a pair of (predicate, query supplier):
+
+```java
+@Override
+protected void collectFindQueries(
+        Consumer<Tuple<Predicate<SQLProduct>, Supplier<FindQuery<SQLProduct>>>> queryConsumer) {
+    // Match by SKU if present
+    queryConsumer.accept(Tuple.create(
+            product -> Strings.isFilled(product.getSku()),
+            () -> insertQuery.newFindQuery().where(SQLProduct.SKU)
+    ));
+    // Fallback: match by name + tenant
+    queryConsumer.accept(Tuple.create(
+            product -> Strings.isFilled(product.getName()),
+            () -> insertQuery.newFindQuery()
+                    .where(SQLProduct.NAME)
+                    .where(SQLProduct.TENANT)
+    ));
+}
+```
+
+The predicate determines if the query applies (e.g., only if SKU is filled).
+Queries are tried in order; the first match wins.
+
+## JDBC Batch Operations
+
+`SQLEntityImportHandler` uses JDBC batch queries for performance:
+
+- **`InsertQuery<E>`** — batched INSERT statements
+- **`UpdateQuery<E>`** — batched UPDATE statements
+- **`DeleteQuery<E>`** — batched DELETE statements
+- **`FindQuery<E>`** — SELECT for matching existing records
+
+These are created lazily and reused across the import run. The batch context
+flushes automatically at configurable intervals.
+
+```java
+protected UpdateQuery<E> updateQuery;
+protected InsertQuery<E> insertQuery;
+protected DeleteQuery<E> deleteQuery;
+```
+
+## Importer — The Entry Point
+
+The `Importer` class orchestrates the full import:
+
+```java
+Importer importer = new Importer("product-import");
+try {
+    SQLTenantImportHandler handler = importer.findHandler(SQLProduct.class);
+    for (Context row : rows) {
+        handler.tryCreateOrUpdate(row);
+    }
+} finally {
+    importer.close();  // flushes batches, fires completion events
+}
+```
+
+## Common Mistakes
+
+1. **Forgetting `collectFindQueries()`** — Without find queries, the importer
+   always creates new entities instead of updating existing ones.
+
+2. **Not closing the Importer** — Always close in a `finally` block or
+   try-with-resources. Unclosed importers leave batch queries unflushed.
+
+3. **Modifying entity state in the wrong event** — Use `BeforeCreateOrUpdateEvent`
+   for validation/enrichment. Using `AfterLoadEvent` may be too early since the
+   entity has not been matched to an existing record yet.
+
+4. **Missing `@AutoImport` on fields** — Fields without `@AutoImport` are invisible
+   to the automatic import mapping and must be handled manually.
+
+5. **Not handling `MissingEntityMode`** — Decide what to do when a referenced entity
+   (e.g., a foreign key) is not found: skip, create, or fail.

package/dist/resources/biz/isenguard.md

@@ -0,0 +1,156 @@
+# Isenguard
+
+Isenguard is the built-in rate limiting and firewall facility. It tracks request
+counts per scope (IP, user, tenant) and realm, blocking requests that exceed
+configured limits. It is typically backed by Redis for distributed rate limiting.
+
+## Enabling Isenguard
+
+Isenguard is gated behind a framework flag:
+
+```hocon
+sirius.frameworks {
+    biz.isenguard = true
+}
+```
+
+The `Isenguard` service is registered unconditionally but only enforces limits
+when the framework is enabled and a `Limiter` backend is available.
+
+## Limiter Backends
+
+The limiter strategy is configured via:
+
+```hocon
+isenguard {
+    limiter = "smart"   # default — uses Redis if available, else NOOP
+}
+```
+
+Available strategies:
+- **`smart`** (default) — uses `RedisLimiter` if Redis is available, otherwise
+  falls back to `NOOPLimiter` (no rate limiting).
+- **`redis`** — always use Redis. Fails if Redis is unavailable.
+- **`noop`** — disables rate limiting entirely.
+
+## Rate Limit Scopes
+
+Each rate limit check requires a **scope** (who is being limited) and a **realm**
+(what operation is being limited):
+
+| Scope Type   | Constant                        | Example Value    |
+|--------------|---------------------------------|------------------|
+| Per IP       | `Isenguard.REALM_TYPE_IP`       | `"192.168.1.1"`  |
+| Per Tenant   | `Isenguard.REALM_TYPE_TENANT`   | `"tenant-42"`    |
+| Per User     | `Isenguard.REALM_TYPE_USER`     | `"user-123"`     |
+
+The scope is a free-form string — you decide what to use as the key.
+
+## Checking Rate Limits
+
+### Programmatic API
+
+```java
+@Part
+private Isenguard isenguard;
+
+// Register a call and check if the limit is reached
+boolean blocked = isenguard.registerCallAndCheckRateLimitReached(
+        clientIp,                              // scope
+        "api-calls",                           // realm
+        Isenguard.USE_LIMIT_FROM_CONFIG,       // use configured limit
+        () -> new RateLimitingInfo(tenantId, tenantName, userId)  // info for audit
+);
+
+if (blocked) {
+    throw Exceptions.createHandled()
+                    .withNLSKey("Isenguard.rateLimitReached")
+                    .handle();
+}
+```
+
+An overload accepts a `Runnable` callback that fires once when the limit is first
+reached (useful for audit logging).
+
+### Check Without Counting
+
+```java
+// Does not count as a call — only checks the current state
+boolean alreadyBlocked = isenguard.checkRateLimitReached(clientIp, "api-calls");
+```
+
+## Configuring Limits
+
+Limits are defined per realm in HOCON:
+
+```hocon
+isenguard {
+    limit {
+        api-calls {
+            limit = 100          # max calls per interval
+            intervalSeconds = 60 # check interval in seconds
+        }
+        login-attempts {
+            limit = 5
+            intervalSeconds = 300
+        }
+    }
+}
+```
+
+You can also pass an explicit limit programmatically by providing a non-zero value
+instead of `Isenguard.USE_LIMIT_FROM_CONFIG`.
+
+## RateLimitedEntity
+
+The `RateLimitedEntity` interface is a marker for entities that have rate limits
+applied to them. Implementing it enables the `RateLimitEventsReportJobFactory`
+to offer itself as a matching job for the entity:
+
+```java
+public interface RateLimitedEntity {
+    String getRateLimitScope();
+}
+```
+
+`Tenant` implements `RateLimitedEntity`, so tenants automatically get rate limit
+reporting. Any custom entity can implement this interface:
+
+```java
+public class APIClient extends BizEntity implements RateLimitedEntity {
+    @Override
+    public String getRateLimitScope() {
+        return "api-client-" + getIdAsString();
+    }
+}
+```
+
+## IP Blocking
+
+Isenguard also functions as a firewall. IPs can be blocked permanently or
+temporarily:
+
+```java
+isenguard.blockIP("192.168.1.100");
+```
+
+Blocked IPs receive HTTP 429 (Too Many Requests) responses. The
+`BlockedIPsReportJobFactory` provides a UI for viewing and managing blocked IPs.
+
+## Common Mistakes
+
+1. **Forgetting `USE_LIMIT_FROM_CONFIG`** — Passing `0` as the explicit limit
+   constant means "use config." Passing a non-zero value overrides the config.
+   Accidentally passing `0` when you mean "no limit" does the wrong thing.
+
+2. **Wrong scope granularity** — Rate limiting by IP is too coarse for shared
+   networks (NAT). Rate limiting by user is too fine if you want to limit a
+   tenant's total API usage. Choose the right scope for your use case.
+
+3. **Not providing `RateLimitingInfo`** — The info supplier is called when the
+   limit is first reached to create an audit log entry. Returning null values
+   makes it hard to diagnose issues.
+
+4. **Missing Redis** — With the `smart` limiter (default), rate limiting silently
+   degrades to no-op when Redis is unavailable. In production, ensure Redis is
+   running or use the `redis` limiter to fail fast.