Architecture Specification and Design Authoring

Wrote docs/architecture/specs/architecture-specification.md. Complete formal architecture specification establishing inline fraud evaluation topologies, sub-25ms gRPC contracts, Redis feature hydration, and fail-closed security invariants.

---

skill: arch-spec-authoring

Architecture Specification: Real-Time Fraud Evaluation Engine [SPEC-FRAUD-001]

Summary

This specification establishes the formal architecture, component contracts, operational invariants, and interface definitions for the Real-Time Fraud Evaluation Engine (fraud-engine v2.0) under run ID fraud-spec-arch-001. It evaluates cardholder transactions across 12 banking channels sustaining 12,000 peak queries/second with an availability commitment of 99.999%. It decisively eliminates the catastrophic post-settlement loss vectors demonstrated in incident FRAUD-4938 (where asynchronous background fraud processing permitted an automated botnet to execute $3.2M in fraudulent withdrawals before alerts triggered). The architecture enforces an inline synchronous gRPC evaluation boundary, a sub-15ms in-memory Redis feature store hydration layer, dual-model scoring (lightweight XGBoost combined with a deterministic rule engine), strict fail-closed evaluation fallbacks, and mathematically provable latency budgets.

Detailed Description

Operating fraud detection as an asynchronous background process disconnects risk assessment from transaction authorization. Once funds leave the settlement clearing house, recovery rates drop below 12%. An authoritative fraud engine must sit directly inline in the authorization path, executing feature retrieval, heuristic rule matching, and machine learning scoring within an immutable 25 ms p99 latency envelope.

Payment Gateway Ingress (12,000 req/sec)
                  │
                  ▼ (Synchronous gRPC: `EvaluateTransaction`)
[ Fraud Ingress & Orchestration Gateway ]
  ├── 1. Ingress Validation: Asserts Payload Schema & Cardinality
  └── 2. Parallel Fan-Out (Target: 10 ms SLA)
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
[ Redis Cluster ]    [ Rule Engine: Drools ]
  ├── Entity History   ├── Blacklists / Geovelocity
  └── Sub-4ms Fetch    └── Deterministic Hard Denies
        │                   │
        └─────────┬─────────┘
                  ▼ (Feature Vector Assembly: 48 Attributes)
[ Real-Time Inference: C++ Triton Inference Server ]
  └── XGBoost Quantized Scorer (Latency <= 6 ms)
                  │
                  ▼
[ Decision Synthesizer & Fail-Closed Gate ]
  ├── Score >= 85: Hard Decline (`REJECT_FRAUD_SUSPECTED`)
  ├── Score 60-84: Challenge (`STEP_UP_FIDO2_REQUIRED`)
  └── Score < 60: Approve (`ALLOW_TRANSACTION`)

Criteria and weights

Comparison

Result

Option C is selected. Inline gRPC gateway evaluates transactions synchronously; in-memory Redis feature hydration and C++ inference meet the 25 ms latency budget.

---

Required Mechanisms

1. System Topology & gRPC Service Contract [MC-ST-01]

• Protocol Buffer Definition:

  syntax = "proto3";
  package banking.fraud.v2;
  
  service FraudEvaluationService {
    rpc EvaluateTransaction (FraudRequest) returns (FraudResponse);
  }
  
  message FraudRequest {
    string transaction_id = 1;
    string card_token = 2;
    int64 amount_cents = 3;
    string currency = 4;
    int64 timestamp_epoch_ms = 5;
    string merchant_category_code = 6;
    string terminal_ip = 7;
  }
  
  message FraudResponse {
    string decision = 1; // ALLOW, CHALLENGE, DECLINE
    int32 risk_score = 2; // 0 - 100
    string reason_code = 3;
    int64 evaluation_duration_us = 4;
  }
  

2. Sub-15ms Feature Hydration Pipeline [MC-FH-01]

• Upon request receipt, the engine fans out to Redis Enterprise Cluster in parallel:
  • Fetches rolling 1-hour transaction count, 24-hour velocity, and last known geolocation coordinates.
  • Redis connection pool uses pipelined MGET with socket timeout set to 8 ms.
  • If Redis fails to respond within 8 ms, the feature vector populates with default cold-start attributes and dispatches alert FEATURE_STORE_DEGRADED.

3. Scoring Engine & Dual-Model Inference [MC-SE-01]

Tier 1 (Deterministic Rules): Evaluates high-confidence hard blocks (SANction list match, country embargo match, impossible velocity > 800 km/h). Execution time: < 1 ms.

Tier 2 (ML Inference): Assembles 48-feature tensor and invokes Triton C++ runtime executing quantized XGBoost model:

• Inference execution duration: <= 6 ms.
• Model memory footprint: 140 MB per worker process.

4. Fail-Closed Fallback Decision Protocol [MC-FC-01]

• If total evaluation duration breaches 22 ms or if the inference worker throws an unhandled exception:
  1. Circuit breaker engages immediately.
  2. For transactions > $500, the engine emits DECLINE with diagnostic ERR_FRAUD_EVALUATION_TIMEOUT.
  3. For transactions <= $500, the engine permits a bounded offline risk waiver with mandatory audit log WAIVER_LOW_VALUE_TIMEOUT.

---

Invariants and Contracts

Mandatory Inline Synchronous Gating [INV-SPEC-01]
  Payment transactions must not clear or commit until the inline fraud evaluation returns a terminal response.
  Decoupling fraud evaluation to asynchronous queues for high-value transactions is prohibited.

Hard Twenty-Five Millisecond Latency Budget [INV-SPEC-02]
  The p99 response duration for `EvaluateTransaction` must not exceed 25.0 milliseconds.
  Individual component timeouts are enforced strictly: Network Ingress (2ms), Feature Store (8ms), Inference (10ms).

Deterministic Fail-Closed High-Value Fallback [INV-SPEC-03]
  Any internal engine timeout, worker crash, or unhandled exception on transactions exceeding $500
  must resolve to DECLINE. Fail-open authorization for high-value transactions is barred.

Explicit Unknowns

• Network jitter variance over cross-availability-zone links between Envoy gateway and Redis shards (G-1).
• Memory cache invalidation overhead when propagating 100,000 real-time merchant blacklist updates per hour (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against architecture specification standards:

• Topology Completeness: PASS. Explicit gRPC contract, Redis feature store, and Triton C++ engine.
• Latency Arithmetic: PASS. Component budgets (2ms + 8ms + 10ms = 20ms) sit safely within the 25ms SLA.
• Safety Invariants: PASS. Fail-closed fallback prevents un-screened high-value transaction releases.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-SPEC-01: David O'Reilly to determine whether deep learning neural network models (ONNX Runtime) should replace XGBoost in Q4 if inference latency remains under 8 ms (Owner: David O'Reilly).

Next steps

1. Marcus Vance provisions high-memory EKS node groups optimized for Triton C++ inference.
2. Core Fraud team implements the Protobuf contract and validates sub-15ms Redis pipeline benchmarks.
3. Conduct staging load drill injecting 15,000 TPS to verify p99 latency remains under 25 ms.