Using Agentic AI to Detect Architecture Flaws Before Code Is Written

An insurance policy endorsement case study using machine-readable constraints, architecture graphs, deterministic validation, and traceable architectural trade-offs.

---

The Design That Looked Correct

An endorsement may begin as a small policy change, yet it carries the full weight of the insurance contract. A commercial property policyholder may request a higher building coverage limit, a revised deductible, an additional location, or a different effective date. The request may qualify for straight-through processing, or it may require underwriting referral because it changes exposure, exceeds product rules, or falls outside delegated authority. For a higher building limit requested today but effective next month, the insurer must determine whether approval is required, calculate the premium for the revised exposure, keep the current policy in force until the requested date, and create a new policy version when the endorsement becomes effective. Earlier versions must remain reconstructable because a claim, audit, regulatory inquiry, or premium dispute may later depend on the coverage that applied on a particular date.

The proposed microservices design appears sound. A client submits the request through an API gateway, and an Endorsement Service coordinates with Underwriting, Rating, and Policy Services. Once the endorsement decision is complete, Billing applies the premium adjustment, Documents produces revised policy forms, and Notifications communicates the outcome to the policyholder.

The design is plausible. The review asks whether its critical decisions are explicit, enforceable, and traceable.

The relevant controls may already exist in workflow definitions, API contracts, schemas, state models, or architecture decision records. The concern is not that the service decomposition is inherently wrong, but whether the available artifacts make its guarantees clear enough to verify before coding begins. Underwriting may own the approval decision, Rating the premium calculation, Policy the authoritative in-force policy version, and the Endorsement Service the process. Those boundaries are credible only when the design also establishes which component may advance the endorsement from requested to approved and from approved to effective. Calling the Underwriting Service does not, by itself, demonstrate that activation is prevented until a durable approval for the same endorsement version exists.

Version alignment requires the same precision. A valid underwriting decision or rating result may belong to an earlier revision of the request. Before activation, the approved coverage, accepted premium, requested effective date, and policy version must all refer to the same endorsement version. Otherwise, independently correct results can combine into an incorrect business outcome. The completion boundary must also be deliberate because policy activation, billing, document generation, and notification do not necessarily share the same consistency requirement. A document outage should not invalidate an otherwise valid policy change, while a retry must not duplicate a policy version, premium adjustment, document, or customer communication. The architecture must therefore distinguish the authoritative endorsement path from downstream work that may complete independently.

Effective dates introduce a temporal dimension beyond ordinary workflow status. A future-dated endorsement may be approved today while the current policy remains in force until the requested date. A permitted retroactive endorsement may alter the applicable coverage period after later transactions have already been recorded. The platform must preserve both when coverage applies in the business domain and when the change became known to the system. Without that distinction, policy reconstruction, premium reconciliation, claims evaluation, and downstream synchronization become unreliable.

Experienced architects have always addressed these concerns through domain analysis, design reviews, state modelling, failure analysis, and architectural governance. Agentic AI does not replace that judgment. Its value lies in reviewing requirements and design artifacts systematically, flagging missing or contradictory evidence before coding begins, and connecting each concern to the relevant business rule and architectural element rather than waiting for integration testing or production behaviour to expose it.

This article explores that process. Insurance rules become machine-readable constraints, the proposed design becomes an architecture graph, deterministic validation checks objective conditions, and AI reasoning examines ambiguity, incomplete evidence, hidden dependencies, and tradeoffs. Human architects retain final authority, while findings are classified as confirmed violations, architectural risks, or questions requiring judgment.

From Business Rules to Architectural Constraints

The architecture review begins before any service contract, workflow implementation, or state-transition code exists. Its first task is to convert distributed business knowledge into constraints that can be evaluated mechanically against a proposed design.

The Constraint Compiler is the first agentic capability in the pipeline. It retrieves relevant requirements, underwriting guidelines, product rules, API contracts, architecture decision records, and engineering standards, then decomposes them into candidate architectural invariants. The agent normalizes different wording into a common schema, preserves source traceability and confidence, identifies missing conditions or conflicting interpretations, and routes ambiguity to an architect or insurance-domain expert rather than inventing a rule.

For the endorsement case, the governing rule is precise: a coverage-changing endorsement that requires underwriting review must not become effective until a durable approved decision exists for the same endorsement version. The agent translates that rule into an applicability condition, prohibited transition, evidence predicate, version-correlation requirement, and severity classification.

{
  "constraintId": "END-APPROVAL-001",
  "source": {
    "type": "UNDERWRITING_GUIDELINE",
    "reference": "Synthetic endorsement approval policy"
  },
  "appliesWhen": {
    "coverageChange": true,
    "underwritingRequired": true
  },
  "target": {
    "aggregate": "PolicyEndorsement",
    "transition": "UNDER_REVIEW -> EFFECTIVE"
  },
  "requiredEvidence": {
    "decision": "APPROVED",
    "durable": true,
    "sameEndorsementVersion": true
  },
  "severity": "HARD_VIOLATION",
  "confidence": 0.96,
  "constraintReviewStatus": "HUMAN_APPROVED"
}

A deterministic schema validator verifies that the generated constraint is complete and structurally valid. In the next stage, the aggregate, transition, and evidence identifiers are linked to corresponding nodes and relationships in the architecture graph. This allows the validation engine to determine whether the proposed design permits an endorsement to become effective without a durable approval for the same endorsement version, before any workflow code is written.

At this point, the AI has not declared the architecture flawed. It has produced the requirement-side evidence needed for the review. Flaw detection begins when that evidence is compared with what the proposed architecture permits. The system can then evaluate not merely whether an Underwriting Service appears in a diagram, but whether every architectural path to EFFECTIVE is gated by a durable approval for the exact endorsement version being activated.

Representing the Design as an Architecture Graph

Architects express the endorsement design through diagrams, API contracts, schemas, state models, and ADRs. The Architecture Graph Builder is an agentic capability. Deterministic parsers process artifacts, while model-based extraction interprets diagrams and decisions. Entity resolution normalizes identifiers into typed nodes and relationships.

The graph represents services, bounded contexts, aggregates, authoritative ownership, databases, dependencies, synchronous and asynchronous interactions, state transitions, version bindings, consistency boundaries, and architecture decisions. Each assertion retains its source and confidence; uncertain mappings return to the architect for confirmation.

For this case, the graph records Endorsement as the workflow coordinator and Underwriting, Rating, Policy, and Billing as owners of the underwriting decision, rating result, in-force policy version, and financial transaction. It also captures the activation path, completion dependencies, and bindings among approval, rating, effective date, and policy version, without classifying any omission as a flaw.

{
  "nodes": [
    {
      "id": "EndorsementService",
      "type": "SERVICE",
      "role": "WORKFLOW_COORDINATOR",
      "source": "service-catalog",
      "confidence": 0.99
    },
    {
      "id": "UnderwritingDecision",
      "type": "DOMAIN_DECISION",
      "owner": "UnderwritingService",
      "source": "underwriting-schema",
      "confidence": 0.99
    },
    {
      "id": "RatingResult",
      "type": "DOMAIN_RESULT",
      "owner": "RatingService",
      "source": "rating-schema",
      "confidence": 0.98
    },
    {
      "id": "PolicyVersion",
      "type": "AGGREGATE",
      "owner": "PolicyService",
      "authoritative": true,
      "source": "policy-state-model",
      "confidence": 0.99
    }
  ],
  "relationships": [
    {
      "from": "PolicyEndorsement",
      "to": "PolicyVersion",
      "type": "STATE_TRANSITION",
      "transition": "UNDER_REVIEW -> EFFECTIVE",
      "guardReference": null,
      "confidence": 0.94
    },
    {
      "type": "ACTIVATION_BINDING",
      "members": [
        "UnderwritingDecision",
        "RatingResult",
        "EffectiveDate",
        "PolicyVersion"
      ],
      "bindingReference": null,
      "confidence": 0.92
    },
    {
      "from": "PolicyService",
      "targets": [
        "BillingService",
        "DocumentService",
        "NotificationService"
      ],
      "type": "COMPLETION_DEPENDENCY",
      "mode": "SYNCHRONOUS",
      "confidence": 0.96
    }
  ]
}

This is not intended to become a universal architecture description language. It creates enough design-side evidence for the Agentic AI review to compare the proposed design with the machine-readable constraints and expose missing guarantees before implementation begins.

The Pre-Code Architecture Intelligence Pipeline

The review pipeline receives two versioned inputs: the approved constraint set from the Constraint Compiler and the architecture-graph snapshot from the Architecture Graph Builder. The review layer binds each constraint to the relevant graph nodes and relationships, creates an execution plan, and dispatches checks to the appropriate capabilities.

Figure 2. Pre-Code Architecture Intelligence Pipeline showing how constraints and design evidence are compared before implementation.

The Deterministic Validation Engine evaluates predicates with objective answers. For the endorsement design, it verifies whether every path to EFFECTIVE requires durable underwriting approval, state-transition ownership is explicit, the rating result and policy version reference the same endorsement version, the effective date is bound to that version, and Billing, Documents, and Notifications are blocking activation dependencies.

The Agentic Architecture Review examines what structural checks cannot resolve: ambiguous ownership, missing evidence, hidden coupling, conflicting assumptions across APIs, schemas, state models, and ADRs, incomplete recovery semantics, and competing design alternatives. Each finding is linked to its governing constraint, evaluated graph path, source artifacts, confidence, and recommendation.

The Evidence and Decision Store preserves lineage across requirements, constraints, graph elements, findings, recommendations, accepted risks, and final decisions. Human Architecture Review resolves insurance exceptions, operational constraints, economic trade-offs, and risk acceptance.

Together, the six capabilities form one controlled pipeline. Deterministic validation establishes certainty where possible; Agentic AI is used only where architectural context and judgment are required; architects retain final authority before implementation begins.

Rules First, Agentic AI for Architectural Judgment

This stage receives the bound evidence produced by the review pipeline: a typed constraint from the Constraint Compiler, the corresponding architecture-graph subgraph, and the provenance and confidence attached to both. The objective is not to let a language model review everything, but to separate mechanically provable results from questions requiring architectural judgment.

The Deterministic Validation Engine evaluates whether an approval prerequisite is absent, a prohibited transition is reachable, multiple services can modify authoritative state, a rating result references a different endorsement version, an effective date is missing, or blocking downstream operations lack defined recovery semantics.

IF endorsement transitions to EFFECTIVE
AND underwritingRequired = true
AND no APPROVED decision exists
for the same endorsementVersion
THEN
  result = FAIL
  classification = HARD_VIOLATION

Each rule returns PASS, FAIL, or UNPROVEN, together with the constraint identifier, evaluated graph path, and supporting evidence. A failed rule receives a severity classification, while an unproven result is routed to the Agentic Architecture Review. Deterministic failures cannot be softened merely because an AI-generated explanation makes the design appear reasonable.

The Agentic Architecture Review examines failed, unproven, or contradictory results. It reviews them from four architectural perspectives. Domain and Ownership Review checks which service owns each business decision and authoritative record. State and Consistency Review checks whether state transitions, endorsement versions, rating results, and effective dates remain aligned. Coupling and Resilience Review examines blocking dependencies, failure propagation, retries, recovery, and opportunities for asynchronous processing. Architecture Critic and Alternatives Review challenges the proposed design and compares safer or simpler alternatives.

These perspectives may run as specialized sub-agents coordinated within the Agentic Architecture Review capability, or as four governed review roles executed by a single agentic workflow. The agent produces structured reasoning, affected components, confidence, and candidate remediations. AI interprets the evidence and proposes alternatives; deterministic rules establish certainty, and the architect retains final authority before implementation begins.

What the Agentic Review Finds

The pipeline converts deterministic results and agentic reasoning into evidence-backed findings rather than a generic architecture score. The Deterministic Validation Engine establishes the detected condition, while the Agentic Architecture Review examines context, conflicting artifacts, undocumented assumptions, operational impact, and possible remediation. Every finding preserves lineage from requirement to constraint, graph elements, source evidence, classification, confidence, and recommendation.

For the endorsement design, approval enforcement is a confirmed violation. The graph contains a reachable path to EFFECTIVE without proof of a durable approved underwriting decision for the same endorsement version.

{
  "findingId": "F-001",
  "requirement": "Underwriting approval before policy effectiveness",
  "constraintId": "END-APPROVAL-001",
  "graphElements": [
    "PolicyEndorsement",
    "UnderwritingDecision",
    "PolicyVersion:EFFECTIVE"
  ],
  "detectedCondition": "Activation path has no durable same-version approval guard",
  "result": "FAIL",
  "classification": "HARD_VIOLATION",
  "confidence": 0.97,
  "evidenceRefs": [
    "underwriting-guideline",
    "policy-state-model"
  ],
  "recommendation": "Enforce approval and version binding at the policy activation boundary"
}

The remaining findings require more careful classification:

Finding	Classification	Evidence and required decision
State-transition ownership	OWNERSHIP_AMBIGUITY	Authority across REQUESTED, UNDER_REVIEW, APPROVED, EFFECTIVE, and CLOSED is unclear. It becomes a violation only if multiple services can independently modify the authoritative endorsement state.
Version alignment	CONSISTENCY_RISK	Underwriting approval, accepted rating result, effective date, and policy version lack one explicit endorsement-version binding.
Downstream completion	RESILIENCE_RISK	Billing, Documents, and Notifications block completion without defined timeout, retry, idempotency, compensation, or independent completion semantics.
Effective-date model	HUMAN_DECISION_REQUIRED	Future-dated and permitted retroactive endorsements require an explicit temporal model agreed with underwriting and product stakeholders.

The output therefore shows not only what may be wrong, but why the conclusion was reached, how certain it is, and which architectural decision must be resolved before implementation begins.

From Findings to the Corrected Architecture

The remediation stage does not allow Agentic AI to generate one recommendation and declare it correct. The Architecture Critic and Alternatives perspective generates and ranks candidate graph deltas, evaluating each against the violated constraints, ownership boundaries, consistency requirements, resilience objectives, insurance operating rules, and implementation consequences. For this endorsement flow, the alternatives include synchronous underwriting approval, a pending-underwriting state, workflow or saga coordination, event-driven choreography, activation followed by compensation, temporal policy versioning, and synchronous versus asynchronous downstream completion.

The selected design preserves explicit domain ownership. The Endorsement Orchestrator owns workflow progression; Underwriting Service owns the underwriting decision; Rating Service owns the accepted rating result; Policy Service owns the authoritative in-force policy version; and Billing Service owns the financial transaction. The state model becomes explicit through REQUESTED, UNDER_REVIEW, APPROVED, REJECTED, SCHEDULED, EFFECTIVE, and CLOSED.

Figure 3. Corrected Policy Endorsement Architecture. The architect-approved target state enforces approval and version alignment at the Policy Service boundary, then moves Billing, Documents, and Notifications outside the policy-activation path.

When underwriting is required, Policy Service accepts activation only after verifying a durable APPROVED decision, accepted rating result, requested date, effective date, and matching endorsementVersion. Future-dated endorsements remain scheduled while the current policy stays in force. Permitted retroactive endorsements require an explicit product rule, underwriting authority, audit evidence, and human approval.

After Policy Service commits the authoritative policy version and outbox record atomically, PolicyEndorsementActivated is published through an event broker. Billing, Documents, and Notifications consume the event independently, so a temporary downstream failure does not reverse or block a valid policy activation. Each consumer must handle duplicate delivery and recoverable failures through idempotency, retry, and reconciliation controls. Durable policy versions and transition evidence preserve reconstructable history.

The agent regenerates the architecture graph, reruns deterministic validation, and records an ADR containing the selected option, supporting constraints, alternatives considered, trade-offs, accepted risks, and architect approval. The result is a corrected, traceable architecture before implementation begins, not automatically generated production code.

Where Human Judgment Is Required

The Architecture Intelligence capability can test explicit constraints, detect structural contradictions, identify missing evidence, classify risks, challenge assumptions, compare alternatives, and preserve traceability. It should not independently determine which business objective has the highest priority, whether an exception is economically justified, whether a known risk should be accepted, how conflicting insurance policies should be interpreted, whether additional operational complexity is acceptable, or whether the architecture receives final approval.

Human review occurs at explicit points in the workflow. Insurance-domain experts confirm inferred business rules before they become enforced constraints. Architects resolve UNPROVEN findings, contradictory artifacts, and low-confidence graph mappings. They also determine whether the implementation and operational cost of a proposed remediation is justified by the risk it removes. The agents should present evidence, affected components, alternatives, consequences, and confidence rather than convert uncertainty into approval.

The human architect remains accountable for trade-offs, exceptions, risk acceptance, and the final decision to release the architecture for implementation.

Conclusion

Architecture flaws rarely begin in code. They begin when business rules, ownership boundaries, version relationships, temporal behavior, consistency guarantees, failure policies, or architectural decisions remain implicit. Agentic AI should therefore do more than generate diagrams or repeat architecture terminology. It should help architects verify, before implementation, whether a proposed design satisfies those guarantees.

The policy endorsement case shows how this becomes practical. Machine-readable constraints are evaluated against structured architecture evidence. Deterministic checks establish what can be proven, contextual AI reasoning investigates ambiguity and competing alternatives, and traceable findings connect each concern to its source evidence and required decision. Human architects still resolve trade-offs, exceptions, and accepted risks. Together, these capabilities make architecture review earlier, more rigorous, explainable, and defensible before design assumptions become code.