> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairoconnect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagrams

> Integration flow and scoring lifecycle in Kairo Shield

## Typical integration flow

```mermaid theme={null}
sequenceDiagram
    participant F as Your fintech
    participant API as Kairo Shield API
    participant W as Your webhook

    F->>API: POST /score (X-API-Key)
    API-->>F: fraud_score, decision, top_features
    API->>W: POST transaction.* (optional)

    Note over F: Apply decision (APPROVE / REVIEW / REJECT)

    F->>API: POST /feedback (when fraud or legitimate confirmed)
    API->>W: POST feedback.received (optional)
```

## Scoring decisions

```mermaid theme={null}
flowchart LR
    A[POST /score] --> B{Rules}
    B -->|Rule fires| C[decision_source: RULES]
    B -->|No rule| D[ML model]
    D --> E{fraud_score vs thresholds}
    E -->|LOW| F[APPROVE]
    E -->|MEDIUM/HIGH| G[REVIEW]
    E -->|CRITICAL| H[REJECT]
```

## Webhook events per transaction

```mermaid theme={null}
flowchart TD
    S[Transaction scored] --> B{decision}
    B -->|REJECT| E1[transaction.blocked]
    B -->|REVIEW or HIGH/CRITICAL| E2[transaction.high_risk]
    B -->|APPROVE or LOW/MEDIUM| E3[transaction.scored]
```

Only **one** transaction event is sent per score (the most specific).

## Data privacy

```mermaid theme={null}
flowchart LR
    subgraph Client
        PII[PII in your system]
        H[Local SHA-256]
    end
    subgraph Kairo_Shield
        API[Scoring API]
        ML[Model + rules]
    end
    PII --> H
    H -->|user_token, ip_hash| API
    API --> ML
```

Never send plaintext PII to Kairo Shield.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.