# recepbaykara/fraud-guard architecture

> Architecture diagram of the GitHub repository recepbaykara/fraud-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/recepbaykara/fraud-guard
- Repository: https://github.com/recepbaykara/fraud-guard

## Overview

Fraud Guard is a real-time fraud-detection plugin running inside Kong’s data plane. Its documented request path extracts a transaction, checks whitelists, evaluates rules against Redis-backed context, scores violations, applies shadow/enforce behavior, and reports results through logs, a webhook, and response headers. Rule categories and supporting detectors are shown as distinct capabilities. No source excerpts were provided, so relationships are limited to the README’s documented flow; paths for undocumented implementation details use their enclosing directories where appropriate.

Main entry points: [`modules/rule_engine.lua`](https://github.com/recepbaykara/fraud-guard/blob/main/modules/rule_engine.lua) (Rule engine), [`modules/execution_mode.lua`](https://github.com/recepbaykara/fraud-guard/blob/main/modules/execution_mode.lua) (Execution mode), [`modules/transaction_extractor.lua`](https://github.com/recepbaykara/fraud-guard/blob/main/modules/transaction_extractor.lua) (Transaction extraction), [`modules`](https://github.com/recepbaykara/fraud-guard/tree/main/modules) (Whitelist check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_extract["Transaction extraction"]
  node_whitelist["Whitelist check"]
end

subgraph group_detection["Fraud detection"]
  node_rule_engine["Rule engine<br/>[rule_engine.lua]"]
  node_account_rules["Account rules<br/>[account_rules.lua]"]
  node_pos_rules["POS rules<br/>[pos_rules.lua]"]
  node_transfer_rules["Transfer rules<br/>[transfer_rules.lua]"]
  node_mobile_rules["Mobile rules<br/>[mobile_rules.lua]"]
  node_api_rules["API security rules"]
  node_amount["Amount detector<br/>[amount.lua]"]
  node_geo["Geographic detector<br/>[geo.lua]"]
  node_pattern["Pattern detector<br/>[pattern.lua]"]
  node_velocity["Velocity detector<br/>[velocity.lua]"]
end

subgraph group_decision["Decision and state"]
  node_scorer["Risk scoring<br/>[scorer.lua]"]
  node_execution["Execution mode<br/>[execution_mode.lua]"]
  node_fail_mode["Failure mode<br/>[fail_mode.lua]"]
  node_cache["Redis cache<br/>[cache.lua]"]
  node_redis_adapter["Redis adapter<br/>[redis_adapter.lua]"]
end

subgraph group_reporting["Reporting"]
  node_logger["Compliance logging<br/>[logger.lua]"]
  node_response["Kong response<br/>[handler.lua]"]
end

node_client(("API client"))
node_redis[("Redis")]
node_webhook(("Webhook receiver"))

node_client -->|"submits transaction"| node_extract
node_extract -->|"checks whitelist"| node_whitelist
node_whitelist -->|"connects to"| node_redis
node_redis -->|"provides context"| node_rule_engine
node_rule_engine -->|"runs rule set"| node_account_rules
node_rule_engine -->|"runs rule set"| node_pos_rules
node_rule_engine -->|"runs rule set"| node_transfer_rules
node_rule_engine -->|"runs rule set"| node_mobile_rules
node_rule_engine -->|"runs rules"| node_api_rules
node_rule_engine -->|"scores violations"| node_scorer
node_scorer -->|"passes score"| node_execution
node_execution -->|"applies failure policy"| node_fail_mode
node_execution -->|"logs result"| node_logger
node_execution -->|"sends webhook"| node_webhook
node_execution -->|"sets response headers"| node_response
node_redis_adapter -.->|"accesses"| node_redis
node_cache -.->|"delegates to"| node_redis_adapter

click node_extract "https://github.com/recepbaykara/fraud-guard/blob/main/modules/transaction_extractor.lua"
click node_whitelist "https://github.com/recepbaykara/fraud-guard/tree/main/modules"
click node_rule_engine "https://github.com/recepbaykara/fraud-guard/blob/main/modules/rule_engine.lua"
click node_account_rules "https://github.com/recepbaykara/fraud-guard/blob/main/rules/account_rules.lua"
click node_pos_rules "https://github.com/recepbaykara/fraud-guard/blob/main/rules/pos_rules.lua"
click node_transfer_rules "https://github.com/recepbaykara/fraud-guard/blob/main/rules/transfer_rules.lua"
click node_mobile_rules "https://github.com/recepbaykara/fraud-guard/blob/main/rules/mobile_rules.lua"
click node_api_rules "https://github.com/recepbaykara/fraud-guard/blob/main/rules/api_security_rules.lua"
click node_amount "https://github.com/recepbaykara/fraud-guard/blob/main/detectors/amount.lua"
click node_geo "https://github.com/recepbaykara/fraud-guard/blob/main/detectors/geo.lua"
click node_pattern "https://github.com/recepbaykara/fraud-guard/blob/main/detectors/pattern.lua"
click node_velocity "https://github.com/recepbaykara/fraud-guard/blob/main/detectors/velocity.lua"
click node_scorer "https://github.com/recepbaykara/fraud-guard/blob/main/utils/scorer.lua"
click node_execution "https://github.com/recepbaykara/fraud-guard/blob/main/modules/execution_mode.lua"
click node_fail_mode "https://github.com/recepbaykara/fraud-guard/blob/main/modules/fail_mode.lua"
click node_cache "https://github.com/recepbaykara/fraud-guard/blob/main/storage/cache.lua"
click node_redis_adapter "https://github.com/recepbaykara/fraud-guard/blob/main/storage/redis_adapter.lua"
click node_logger "https://github.com/recepbaykara/fraud-guard/blob/main/utils/logger.lua"
click node_response "https://github.com/recepbaykara/fraud-guard/blob/main/handler.lua"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extract,node_whitelist,node_client toneBlue
class node_rule_engine,node_account_rules,node_pos_rules,node_transfer_rules,node_mobile_rules,node_api_rules,node_amount,node_geo,node_pattern,node_velocity,node_redis toneAmber
class node_scorer,node_execution,node_fail_mode,node_cache,node_redis_adapter,node_webhook toneMint
class node_logger,node_response toneRose
```

## Components

### Request handling

- [Transaction extraction](https://github.com/recepbaykara/fraud-guard/blob/main/modules/transaction_extractor.lua): `modules/transaction_extractor.lua`
- [Whitelist check](https://github.com/recepbaykara/fraud-guard/tree/main/modules): `modules`

### Fraud detection

- [Rule engine](https://github.com/recepbaykara/fraud-guard/blob/main/modules/rule_engine.lua): `modules/rule_engine.lua`
- [Account rules](https://github.com/recepbaykara/fraud-guard/blob/main/rules/account_rules.lua): `rules/account_rules.lua`
- [POS rules](https://github.com/recepbaykara/fraud-guard/blob/main/rules/pos_rules.lua): `rules/pos_rules.lua`
- [Transfer rules](https://github.com/recepbaykara/fraud-guard/blob/main/rules/transfer_rules.lua): `rules/transfer_rules.lua`
- [Mobile rules](https://github.com/recepbaykara/fraud-guard/blob/main/rules/mobile_rules.lua): `rules/mobile_rules.lua`
- [API security rules](https://github.com/recepbaykara/fraud-guard/blob/main/rules/api_security_rules.lua): `rules/api_security_rules.lua`
- [Amount detector](https://github.com/recepbaykara/fraud-guard/blob/main/detectors/amount.lua): `detectors/amount.lua`
- [Geographic detector](https://github.com/recepbaykara/fraud-guard/blob/main/detectors/geo.lua): `detectors/geo.lua`
- [Pattern detector](https://github.com/recepbaykara/fraud-guard/blob/main/detectors/pattern.lua): `detectors/pattern.lua`
- [Velocity detector](https://github.com/recepbaykara/fraud-guard/blob/main/detectors/velocity.lua): `detectors/velocity.lua`

### Decision and state

- [Risk scoring](https://github.com/recepbaykara/fraud-guard/blob/main/utils/scorer.lua): `utils/scorer.lua`
- [Execution mode](https://github.com/recepbaykara/fraud-guard/blob/main/modules/execution_mode.lua): `modules/execution_mode.lua`
- [Failure mode](https://github.com/recepbaykara/fraud-guard/blob/main/modules/fail_mode.lua): `modules/fail_mode.lua`
- [Redis cache](https://github.com/recepbaykara/fraud-guard/blob/main/storage/cache.lua): `storage/cache.lua`
- [Redis adapter](https://github.com/recepbaykara/fraud-guard/blob/main/storage/redis_adapter.lua): `storage/redis_adapter.lua`

### Reporting

- [Compliance logging](https://github.com/recepbaykara/fraud-guard/blob/main/utils/logger.lua): `utils/logger.lua`
- [Kong response](https://github.com/recepbaykara/fraud-guard/blob/main/handler.lua): `handler.lua`

### Other components

- **API client**
- **Redis**
- **Webhook receiver**

## Connections

- API client → Transaction extraction: submits transaction (evidence: `README.md`)
- Transaction extraction → Whitelist check: checks whitelist (evidence: `README.md`)
- Whitelist check → Redis: connects to (evidence: `README.md`)
- Redis → Rule engine: provides context (evidence: `README.md`)
- Rule engine → Account rules: runs rule set (evidence: `README.md`)
- Rule engine → POS rules: runs rule set (evidence: `README.md`)
- Rule engine → Transfer rules: runs rule set (evidence: `README.md`)
- Rule engine → Mobile rules: runs rule set (evidence: `README.md`)
- Rule engine → API security rules: runs rules (evidence: `README.md`)
- Rule engine → Risk scoring: scores violations (evidence: `README.md`)
- Risk scoring → Execution mode: passes score (evidence: `README.md`)
- Execution mode → Failure mode: applies failure policy (evidence: `README.md`)
- Execution mode → Compliance logging: logs result (evidence: `README.md`)
- Execution mode → Webhook receiver: sends webhook (evidence: `README.md`)
- Execution mode → Kong response: sets response headers (evidence: `README.md`)
- Redis adapter → Redis: accesses
- Redis cache → Redis adapter: delegates to
