Turn incoming events into reliable actions.

docker compose -f tengen/docker-compose.yml --profile rabbitmq up -d db rabbitmq

cd tengen
./mvnw spring-boot:run

cd frontend
npm ci
npm run dev

First workflow

1. Sign in. Open the admin console and use the configured admin credentials.
2. Create an ingestion key. Open API Keys, choose a name, and optionally scope event types and sources.
3. Create a rule. Start with a condition rule and use data.amount >= 1000 as the condition.
4. Send an event. Use the HTTP example in the next section with the raw key shown once at creation time.
5. Inspect the result. Use Events to see the accepted event, rule outcome, event-time status, and any webhook delivery.

{
  "type": "payment",
  "source": "billing",
  "timestamp": "2026-08-04T14:30:00Z",
  "data": {
    "amount": 2500,
    "currency": "PHP",
    "country": "PH",
    "userId": "user-123"
  }
}

What happens to an accepted event?

curl -X POST http://localhost:8080/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tg_your_raw_key" \
  -H "Idempotency-Key: payment-123" \
  -d '{
    "type": "payment",
    "source": "billing",
    "timestamp": "2026-08-04T14:30:00Z",
    "data": {
      "amount": 2500,
      "country": "PH"
    }
  }'

Producer response

Every accepted request returns HTTP 200. The response mode belongs to the API key, so processing is always complete even when the producer receives a compact projection.

{
  "status": "accepted",
  "matched": true,
  "rules": ["large-payment"],
  "queuedRules": [],
  "suppressedRules": [],
  "eventTimeStatus": "ON_TIME"
}

{
  "event": { "type": "payment", "source": "billing", "data": { "amount": 2500 } },
  "status": "accepted",
  "matched": true,
  "rules": ["large-payment"],
  "queuedRules": ["large-payment"],
  "aggregates": {},
  "sequences": {},
  "suppressedRules": [],
  "eventTimeStatus": "ON_TIME"
}

Safe retries with Idempotency-Key

Use one idempotency key for each logical event. The key is scoped to the API key that sent it.

HTTP ingestion guardrails

• Request bodies are limited by INGESTION_MAX_BODY_BYTES (1 MiB by default).
• Each API key is rate-limited by INGESTION_RATE_LIMIT_PER_MINUTE (600 by default). A limited request returns 429 and a Retry-After header.
• Event timestamps too far into the future are rejected. The default maximum future skew is five minutes.
• type and source are required; data must be a JSON object.

Local broker and topology

docker compose -f tengen/docker-compose.yml --profile rabbitmq up -d db rabbitmq

tengen.input       --events------> tengen.events
tengen.dead-letter --dead-letter-> tengen.events.dlq

Configure the connector

1. Open API Keys and create an active key whose allowed event types and sources cover broker messages.
2. Open Connectors and choose RabbitMQ.
3. Enter the broker connection, queue, dead-letter, API-key, and retry settings described below.
4. Choose Save draft. Tengen increments the configuration version and clears the previous test result.
5. Choose Test connection. The test checks credentials, virtual-host access, the input queue, and the dead-letter exchange.
6. Choose Enable consumption. Enabling is blocked until the current saved version has a successful test.

Message contract

Publish persistent UTF-8 JSON with content_type=application/json and a unique AMQP message_id. The body uses the same event envelope as HTTP ingestion.

{
  "type": "payment",
  "source": "billing",
  "timestamp": "2026-08-04T14:30:00Z",
  "data": { "amount": 2500, "country": "PH" }
}

RabbitMQ watermark header

Watermark processing is enabled by default. To explicitly opt out for one message, set the AMQP header below:

x-tengen-watermark: false

• Missing, malformed, or non-false values keep watermark processing enabled.
• An opted-out message is still API-key validated, persisted, and evaluated.
• An opted-out message does not create or update a watermark and has no event-time lateness classification.
• This header is a processing hint, not a security control.

Common creation workflow

1. Open Rules and choose New Rule.
2. Enter a unique rule name. Rule names are limited to 100 characters.
3. Choose one of CONDITION, AGGREGATE, SEQUENCE, or ABSENCE.
4. Choose an action: LOG records the match only; WEBHOOK also creates a delivery intent.
5. Fill in the type/source, conditions, windows, grouping, threshold, and webhook options required by the selected rule type.
6. Leave Active selected when the rule should start evaluating immediately, or save it inactive for review.
7. Choose Save Rule. Tengen validates the complete rule before it can execute.

Shared rule fields

Conditions: Visual Builder or Raw Aviator

The visual builder creates an Aviator expression. Use groups to combine conditions with AND or OR. Each leaf has a field, operator, and value.

data.amount >= 1000 && data.country == 'PH'

Raw expressions are validated by Aviator before the rule is saved or activated. The default maximum expression length is 10,000 characters.

Example: high-value payment

How to create one

1. Choose AGGREGATE as the rule type.
2. Set the event type, source, and optional condition that selects events for the aggregate.
3. Choose an aggregate function. COUNT does not need an aggregate field; the other functions require a numeric dotted path such as data.amount.
4. Set the window in seconds and the threshold. The current event is included in the calculation.
5. Optionally set Group by field to maintain separate totals per user, account, device, or order.
6. Choose ONCE_PER_WINDOW when a webhook should be reserved once per fixed event-time bucket rather than once for every matching event.

Rule type:     AGGREGATE
Event type:    login.failed
Source:        identity
Aggregate:     COUNT
Window:        300 seconds
Threshold:     5
Group by:      data.userId

Configure the sequence

1. Choose SEQUENCE as the rule type.
2. Keep the default two steps or add steps up to a maximum of five. Use the arrows to reorder them.
3. For every step, enter an event type, source, and condition.
4. Set the sequence window in seconds.
5. Optionally set one shared group-by path, such as data.orderId or data.userId. Every step must resolve to the same value for correlation.
6. Use LOG or WEBHOOK. Sequence webhooks use EVERY_MATCH; the edge and once-per-window trigger modes are not available for sequence rules.

Runtime state reset

Updating, activating, deactivating, archiving, unarchiving, or restoring a rule clears action cooldown/window state and cancels active sequence or pending absence instances for that rule. This prevents a new configuration from inheriting progress from an older revision.

Configure a webhook rule

1. Choose WEBHOOK in the rule action field.
2. Enter a callback URL. It must be HTTPS and use a public host/address.
3. Choose the trigger mode appropriate for the rule.
4. Optionally set a cooldown in seconds. Cooldown controls repeated delivery, not whether the rule matches.
5. Save and activate the rule. The delivery worker will process the outbox automatically when enabled.

Callback URL restrictions

Tengen validates the URL when the rule is saved and again before delivery. The destination must:

• Use https://.
• Contain a host and no embedded username/password.
• Contain no URL fragment.
• Resolve to public addresses. Localhost, loopback, private, link-local, multicast, metadata-service, documentation, and other reserved ranges are rejected.
• Be reachable without relying on redirects; the client does not follow redirects.

For local development, use a public HTTPS tunnel or disable the worker. http://localhost callbacks are intentionally rejected.

Delivery payload

Each delivery is a JSON document containing the original event and the rule evaluation details available for that match.

{
  "event": {
    "type": "payment",
    "source": "billing",
    "timestamp": "2026-08-04T14:30:00Z",
    "data": { "amount": 2500, "country": "PH" }
  },
  "status": "accepted",
  "matched": true,
  "rules": ["large-payment"],
  "aggregates": {},
  "sequences": {}
}

Aggregate matches add an entry under aggregates. Completed sequences add an entry under sequences. Absence triggers add an entry under absences with the start event, expected event, deadline, group, and triggering watermark.

Signed delivery headers

The signature is computed over <timestamp>.<raw-json-body> with WEBHOOK_SIGNING_SECRET as the HMAC key. Verify against the raw request body before parsing or reserializing JSON.

message = X-Tengen-Timestamp + "." + raw_request_body
signature = HMAC_SHA256_HEX(WEBHOOK_SIGNING_SECRET, message)
expected = "v1=" + signature

Delivery lifecycle

• 2xx responses are successful.
• Timeouts, connection failures, 408, 429, and 5xx responses are retryable.
• Permanent failures and exhausted attempts become DEAD_LETTER.
• The default worker allows eight attempts with exponential backoff capped at 15 minutes.
• Delivery is at least once. A receiver should deduplicate by X-Tengen-Delivery-Id.

Delivery history

Open Deliveries to filter by status, rule, event, time range, or search text. Open a row to inspect the destination, payload metadata, attempts, status code, error, and timeline. Retry a dead-lettered delivery from its detail view; the same outbox record is reused.

Available filters

Create a replay

1. Open Replays.
2. Select a rule and an immutable revision.
3. Select an occurred-time range. The start is inclusive and the end is exclusive.
4. Optionally filter the input events by API key.
5. Choose Start replay job. The request is immutable after creation.

Replay control requests use the job version in If-Match. Refresh the job before controlling it when another operator may have changed its state.

Sample .env files

Save one of these examples as .env in the repository root before running Docker Compose. The values below are examples; do not commit real credentials or production secrets.

# .env - local Docker Compose
SPRING_PROFILES_ACTIVE=
ADMIN_USER=admin
ADMIN_PASSWORD=admin
JWT_SECRET=dev-secret-change-me-please-32-bytes-min
WEBHOOK_SIGNING_SECRET=dev-webhook-signing-secret-change-me
CORS_ALLOWED_ORIGINS=http://localhost:3000
WEBHOOK_WORKER_ENABLED=true
TENGEN_ABSENCE_WORKER_ENABLED=true
TENGEN_REPLAY_WORKER_ENABLED=true
DB_PORT=5432
APP_PORT=8080
FRONTEND_PORT=3000
RABBITMQ_AMQP_PORT=5672
RABBITMQ_MANAGEMENT_PORT=15672
RABBITMQ_DEFAULT_USER=tengen
RABBITMQ_DEFAULT_PASS=tengen

# Optional: required before saving a RabbitMQ connector
# TENGEN_CONNECTOR_MASTER_KEY=base64-encoded-random-32-byte-key

# .env - production
SPRING_PROFILES_ACTIVE=prod
ADMIN_USER=admin
ADMIN_PASSWORD=replace-with-a-strong-password
JWT_SECRET=replace-with-a-random-secret-at-least-32-bytes
WEBHOOK_SIGNING_SECRET=replace-with-another-random-secret-at-least-32-bytes
CORS_ALLOWED_ORIGINS=https://console.example.com
WEBHOOK_WORKER_ENABLED=true
TENGEN_ABSENCE_WORKER_ENABLED=true
TENGEN_REPLAY_WORKER_ENABLED=true
RETENTION_ENABLED=true
RETENTION_DAYS=90
TENGEN_CONNECTOR_MASTER_KEY=replace-with-base64-encoded-random-32-byte-key
TENGEN_RABBITMQ_ALLOWED_HOSTS=rabbitmq.internal.example
DB_PORT=5432
APP_PORT=8080
FRONTEND_PORT=3000

Minimum production environment

SPRING_PROFILES_ACTIVE=prod
ADMIN_PASSWORD=replace-with-a-strong-password
JWT_SECRET=replace-with-a-random-secret-at-least-32-bytes
WEBHOOK_SIGNING_SECRET=replace-with-another-random-secret
CORS_ALLOWED_ORIGINS=https://your-console.example

If RabbitMQ is used, also configure TENGEN_CONNECTOR_MASTER_KEY and an exact TENGEN_RABBITMQ_ALLOWED_HOSTS list.

Build and start

docker compose --env-file .env -f tengen/docker-compose.yml up --build -d

Add --profile rabbitmq when the RabbitMQ service should start with the stack.

Authentication model

• Admin endpoints use Authorization: Bearer <access-token> when called directly.
• POST /api/auth/login returns an access/refresh token pair. The frontend stores these in httpOnly cookies through its session route.
• Event ingestion uses X-API-Key, not the admin JWT.
• Public health probes are the liveness and readiness endpoints. Other API routes are protected.

Get an admin access token

curl -sS -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

Use the returned accessToken in an Authorization header for admin endpoints. Use the returned refreshToken with /api/auth/refresh when the access token expires.

Endpoint index

Paging and filter parameters

Create a condition rule through the API

curl -sS -X POST http://localhost:8080/api/rules \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "large-payment",
    "ruleType": "CONDITION",
    "action": "LOG",
    "eventType": "payment",
    "source": "billing",
    "conditionScript": "data.amount >= 1000",
    "threshold": 0,
    "active": true,
    "sequenceSteps": []
  }'

For aggregate, sequence, absence, or webhook rules, add the fields described in the rule sections above. Keep the request contract stable: the backend validates the combination of fields for the selected rule type and action.