Architecture

Overview

Conduvia is the governed platform boundary. It acts as a transparent checkpoint: valid requests pass through unchanged, invalid requests are rejected with platform-shaped errors. Neither producers nor downstream systems know Conduvia exists by name.

Conduvia validates the contract. Domain services validate the meaning.

The responsibility split is clear: Conduvia owns boundary admission, DTO/contract validation, schema/version admission, route/policy enforcement, idempotency, rate/size controls, runtime delivery reliability, retry/DLQ, and platform-level PBAC authorization. The workflow engine owns orchestration, workflow state, compensation, and AI agent governance. Domain services own domain state, business logic, and business validation.

Two-Layer Model

Layer 1 — Conduvia Edge (Policy Intercept)

A synchronous interceptor at the platform boundary. Every request passes through this layer. Binary decision: admit or reject.

conduvia-policy-core provides transport-neutral validation and policy logic. conduvia-edge-gateway binds the policy core to the chosen edge technology.

Layer 2 — Conduvia Runtime (Managed Delivery)

An asynchronous execution layer behind the edge. Handles delivery, retries, and operational control after a request has been admitted.

conduvia-manager is the control plane for connector lifecycle. conduvia-worker is the data plane for sink task execution.

Sync:  Producer → Conduvia Edge → validated → direct forward → downstream
Async: Producer → Conduvia Edge → validated → Kafka → workers → delivery

Validation Chain

Executed in strict order. Short-circuits on first failure:

1. Route/alias existence and active-state check
2. Data-plane authorization (role/scope/tenant/producer)
3. Request shape / envelope validation
4. Header validation
5. Schema version validity / compatibility
6. Payload schema validation (DTO)
7. Transforms
8. Idempotency check
9. Rate limits and body size limits
10. Accept and forward, or reject

Steps 1 and 2 execute before schema validation to avoid expensive validation work for unauthorized traffic.

Three Validation Bands

Band 1 (always Conduvia): @NotNull, @Size, @Pattern, enum membership, array limits, nested DTO, payload size, header format, schema version.

Band 2 (Conduvia if cheap + deterministic): Cross-field checks, mutual exclusion, bounded prompt injection (AI aliases only).

Band 3 (never Conduvia): Database-backed checks, state transitions, cross-entity consistency, service calls, business authorization.

Schema Governance

Schema versions are immutable contracts with a lifecycle. Once Active, a version cannot be changed — any change requires a new version number.

Draft → Active → Deprecated → Blocked → Retired

Critical: Deprecated → Blocked requires platform approval (usage metrics + owner acknowledgement + platform-admin sign-off). A timer alone cannot trigger this transition.

PBAC Authorization

Conduvia uses PBAC as a bounded, claim-based enforcement model. RBAC provides default access mapping, ABAC adds approved contextual constraints.

RBAC for clarity. ABAC for precision. PBAC as the overall model.

The approved ABAC attribute vocabulary: role, scope, tenant, producerId, serviceId, alias, environment, region, schemaVersion, schemaLifecycleState, payloadClassification, requestSizeBand, timeWindow.

11 guardrails are enforced. No opaque authorization decisions. Full audit every decision.

Drools Policy Engine

Drools serves as the optional PBAC rule-evaluation engine. Policy is authored in JSON and compiled at registration time into executable-model Drools artifacts. Runtime evaluation uses stateless KIE sessions against immutable request facts.

DENY precedence is implemented through activation group semantics, not salience alone. Only one rule in an activation group fires per session cycle.

Reliability Model

Producers own business intent. Conduvia owns delivery resilience.

Attempt 1 → immediate
Attempt 2 → after 5 minutes
Attempt 3 → after 30 minutes
Attempt 4 → after 2 hours
Attempt 5 → terminal → DLQ if configured

Three failure lanes: Retry (transient), DLQ (terminal delivery failures), Quarantine (suspicious/policy-violating, needs human review).

Standard Envelope

{
  "type": "EVENT_OR_COMMAND_NAME",
  "schemaVersion": "1.0",
  "correlationId": "01JWMXXXXXXXXXXXXX",
  "payload": { "...": "domain-specific fields" }
}

Frozen Principles

These statements take precedence over any document, proposal, or feature request that contradicts them.

“Conduvia is the transparent governed checkpoint at the platform boundary.”

“Conduvia validates the contract. Domain services validate the meaning.”

“As the system grows, Conduvia should grow in throughput, not in intelligence.”

“RBAC for clarity. ABAC for precision. PBAC as the overall model.”

“No DB calls, no downstream service calls, no dynamic business-state lookups in Conduvia authorization.”

“Conduvia governs what enters and leaves the platform. The workflow engine governs how AI agents behave inside it.”