Domain Specification: Configuration Engine

Validated against PRD v1.0 — All FR-CF-* requirements. See Traceability Matrix.

---

1. Context Overview

Bounded Context: configuration
Responsibility: Manage all business-configurable rules: workflow templates, thresholds, approval matrices, document requirements. Every change is versioned and auditable.
Owns: ConfigVersion, WorkflowTemplate, ThresholdConfig, ApprovalMatrix, DocumentRequirement aggregates.
Consumed By: ALL other bounded contexts (read config at invocation).
Events Published: ConfigVersionCreated, ConfigVersionPromoted, ConfigVersionRolledBack.

---

2. Configuration Entities

data class ConfigVersion(
    val versionId: UUID,
    val versionNumber: String,             // "1.0.3"
    val status: VersionStatus,             // DRAFT, TEST, ACTIVE, SUPERSEDED
    val createdBy: UUID,
    val createdAt: Instant,
    val activatedAt: Instant?,
    val workflows: List<WorkflowTemplate>,
    val thresholds: List<ThresholdConfig>,
    val approvalMatrices: List<ApprovalMatrix>,
    val documentRules: List<DocumentRequirement>
)

enum class VersionStatus { DRAFT, TEST, ACTIVE, SUPERSEDED }

---

3. API Contracts

3.1 Get Active Config

GET /api/v1/config/active?moduleType=RISK_RATING&context={jurisdiction:NLD,archetype:CORPORATE}
Authorization: System

Response 200:
{
  "versionId": "uuid",
  "versionNumber": "1.0.3",
  "status": "ACTIVE",
  "activatedAt": "2025-05-20T09:00:00Z",
  "config": {
    "thresholds": [ /* risk score thresholds */ ],
    "approvalMatrix": [ /* who approves what */ ],
    "documentRules": [ /* mandatory documents */ ]
  }
}

3.2 Create Config Version

POST /api/v1/config/versions
Authorization: Bearer <jwt> (ADMIN role)

Request:
{
  "baseVersion": "1.0.3",         // optional: inherit from existing version
  "workflows": [ /* full template definitions */ ],
  "thresholds": [ /* risk thresholds */ ],
  "approvalMatrices": [ /* approval rules */ ],
  "documentRules": [ /* document requirements */ ]
}
Response 201: { "versionId": "uuid", "versionNumber": "1.0.4", "status": "DRAFT" }

3.3 Promote Config Version

POST /api/v1/config/versions/{versionId}/promote
Authorization: Bearer <jwt> (ADMIN role)

Request: { "targetStatus": "ACTIVE" }
Response 200:
{
  "versionId": "uuid",
  "versionNumber": "1.0.4",
  "status": "ACTIVE",
  "previousActiveVersion": "1.0.3",
  "activatedAt": "2025-06-01T15:00:00Z",
  "note": "Running workflow instances continue on v1.0.3. New instances use v1.0.4."
}

3.4 Rollback

POST /api/v1/config/versions/{versionId}/rollback
Authorization: Bearer <jwt> (ADMIN role)

Request: { "reason": "Risk thresholds too aggressive — 60% of customers rated HIGH" }
Response 200:
{
  "rollbackToVersion": "1.0.3",
  "supersededVersion": "1.0.4",
  "reason": "Risk thresholds too aggressive — 60% of customers rated HIGH"
}

3.5 Get Version History

GET /api/v1/config/versions?page=1&limit=20
Authorization: Bearer <jwt>

Response 200:
{
  "items": [
    { "versionNumber": "1.0.4", "status": "ACTIVE", "createdBy": "admin-1", "createdAt": "2025-06-01", "changes": "Updated risk thresholds for LATAM" },
    { "versionNumber": "1.0.3", "status": "SUPERSEDED", "createdBy": "admin-1", "createdAt": "2025-05-20", "changes": "Added Correspondent Banking workflow template" }
  ]
}

---

4. Promotion Pipeline

flowchart LR
    DRAFT --> TEST --> ACTIVE --> SUPERSEDED
    DRAFT -.->|rollback to any previous ACTIVE| SUPERSEDED

• DRAFT: Editable by admin. Not used by any module.
• TEST: Used by test/staging environment. Modules in test use TEST config.
• ACTIVE: Used by production. Exactly one version ACTIVE at a time.
• SUPERSEDED: Previous ACTIVE versions. Immutable. Running workflows that started on this version continue using it until completion.

---

5. Error Handling

Scenario	Behavior
Promote without approval	403 Forbidden. "Config promotion requires secondary admin approval."
Modify SUPERSEDED version	400 Bad Request. "Cannot modify a SUPERSEDED config version. Create a new version."
No ACTIVE version	500 Internal Server Error. "No active configuration version found. Contact administrator."
Rollback to self	400 Bad Request. "Cannot rollback to the currently active version."

---

Spec validated against PRD v1.0 requirements FR-CF-01 through FR-CF-03. The Configuration Engine is the critical path dependency — all other modules depend on it.