# renan-lab/fraud-analysis-go architecture

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

- Interactive diagram: https://gitdiagram.com/renan-lab/fraud-analysis-go
- Repository: https://github.com/renan-lab/fraud-analysis-go

## Overview

This Go service accepts financial transactions over HTTP, validates and publishes them to Kafka, then a worker combines fraud rules with account/card history in Redis and publishes approve/review/block decisions. A simulator can generate realistic or adversarial traffic and record ground truth; an evaluator compares that truth with analyzed events and reports quality metrics and gate failures. The graph preserves these distinct product stages and key platform dependencies. Some subsystems are represented by their exact directories because their implementation was not sampled; their links are limited to documented or excerpted relationships.

Main entry points: [`internal/analysis/service.go`](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/service.go) (Analysis Service), [`cmd/worker/main.go`](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/worker/main.go) (Analysis Worker), [`cmd/simulator/main.go`](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/simulator/main.go) (Simulator CLI), [`cmd/api/routes.go`](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/api/routes.go) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Transaction Ingestion"]
  node_api["HTTP API<br/>[routes.go]"]
  node_ingest_handler["Request Handler<br/>[handler.go]"]
  node_ingest_service["Ingest Service<br/>[service.go]"]
  node_received_event["Received Event"]
end

subgraph group_analysis["Fraud Analysis"]
  node_worker["Analysis Worker<br/>[main.go]"]
  node_analysis_consumer["Event Consumer<br/>[consumer.go]"]
  node_analysis_service["Analysis Service<br/>[service.go]"]
  node_fraud_rules["Fraud Rules"]
  node_feature_store["Feature Store"]
  node_analyzed_event["Analyzed Event"]
end

subgraph group_simulation["Traffic Simulation"]
  node_simulator_cli["Simulator CLI<br/>[main.go]"]
  node_simulator_generator["Traffic Generator"]
  node_scenarios["Traffic Scenarios"]
  node_simulator_sender["Traffic Sender"]
  node_truth_writer["Truth Writer"]
end

subgraph group_evaluation["Decision Evaluation"]
  node_truth_file["Ground Truth<br/>[record.go]"]
  node_evaluator_cli["Evaluator CLI<br/>[main.go]"]
  node_evaluation_service["Evaluation Service<br/>[service.go]"]
  node_evaluation_metrics["Quality Metrics"]
  node_evaluation_report["Evaluation Report<br/>[report.go]"]
end

subgraph group_platform["Shared Infrastructure"]
  node_kafka["Kafka"]
  node_redis[("Redis State")]
  node_kafka_platform["Kafka Client"]
  node_redis_platform["Redis Client<br/>[client.go]"]
end

node_client(("Transaction Client"))

node_client -->|"submits transactions"| node_api
node_api -->|"routes requests"| node_ingest_handler
node_ingest_handler -->|"ingests valid transactions"| node_ingest_service
node_ingest_service -->|"constructs event"| node_received_event
node_ingest_service -->|"publishes event"| node_kafka
node_api -->|"configures producer"| node_kafka_platform
node_worker -->|"configures consumer"| node_kafka_platform
node_worker -->|"connects Redis"| node_redis_platform
node_worker -->|"constructs service"| node_analysis_service
node_worker -->|"wraps service"| node_analysis_consumer
node_kafka -->|"delivers received events"| node_analysis_consumer
node_analysis_consumer -->|"handles event"| node_analysis_service
node_analysis_service -->|"loads and records features"| node_feature_store
node_analysis_service -->|"evaluates rules"| node_fraud_rules
node_feature_store -->|"reads and writes state"| node_redis
node_analysis_service -->|"publishes decision"| node_kafka
node_analysis_service -->|"constructs decision event"| node_analyzed_event
node_simulator_cli -->|"creates generator"| node_simulator_generator
node_simulator_cli -->|"selects sender"| node_simulator_sender
node_simulator_cli -->|"creates optional writer"| node_truth_writer
node_simulator_generator -.->|"generates scenario traffic"| node_scenarios
node_simulator_cli -->|"writes truth records"| node_truth_file
node_simulator_sender -->|"sends HTTP traffic"| node_api
node_evaluator_cli -->|"runs evaluation"| node_evaluation_service
node_evaluator_cli -->|"loads truth"| node_truth_file
node_evaluator_cli -->|"reads analyzed events"| node_kafka
node_evaluation_service -->|"computes quality metrics"| node_evaluation_metrics
node_evaluation_service -->|"returns report"| node_evaluation_report

click node_api "https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/api/routes.go"
click node_ingest_handler "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/ingestion/handler.go"
click node_ingest_service "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/ingestion/service.go"
click node_received_event "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/events/transaction_received.go"
click node_worker "https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/worker/main.go"
click node_analysis_consumer "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/consumer.go"
click node_analysis_service "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/service.go"
click node_fraud_rules "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/analysis"
click node_feature_store "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/featurestore_redis.go"
click node_analyzed_event "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/events/transaction_analyzed.go"
click node_simulator_cli "https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/simulator/main.go"
click node_simulator_generator "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator"
click node_scenarios "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator"
click node_simulator_sender "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator"
click node_truth_writer "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator"
click node_truth_file "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/groundtruth/record.go"
click node_evaluator_cli "https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/evaluator/main.go"
click node_evaluation_service "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/evaluation/service.go"
click node_evaluation_metrics "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/evaluation"
click node_evaluation_report "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/evaluation/report.go"
click node_kafka_platform "https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/platform/kafka"
click node_redis_platform "https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/platform/redis/client.go"

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_api,node_ingest_handler,node_ingest_service,node_received_event,node_client toneBlue
class node_worker,node_analysis_consumer,node_analysis_service,node_fraud_rules,node_feature_store,node_analyzed_event toneAmber
class node_simulator_cli,node_simulator_generator,node_scenarios,node_simulator_sender,node_truth_writer toneMint
class node_truth_file,node_evaluator_cli,node_evaluation_service,node_evaluation_metrics,node_evaluation_report toneRose
class node_kafka,node_redis,node_kafka_platform,node_redis_platform toneIndigo
```

## Components

### Transaction Ingestion

- [HTTP API](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/api/routes.go): `cmd/api/routes.go`
- [Request Handler](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/ingestion/handler.go): `internal/ingestion/handler.go`
- [Ingest Service](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/ingestion/service.go): `internal/ingestion/service.go`
- [Received Event](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/events/transaction_received.go): `internal/events/transaction_received.go`

### Fraud Analysis

- [Analysis Worker](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/worker/main.go): `cmd/worker/main.go`
- [Event Consumer](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/consumer.go): `internal/analysis/consumer.go`
- [Analysis Service](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/service.go): `internal/analysis/service.go`
- [Fraud Rules](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/analysis): `internal/analysis`
- [Feature Store](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/analysis/featurestore_redis.go): `internal/analysis/featurestore_redis.go`
- [Analyzed Event](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/events/transaction_analyzed.go): `internal/events/transaction_analyzed.go`

### Traffic Simulation

- [Simulator CLI](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/simulator/main.go): `cmd/simulator/main.go`
- [Traffic Generator](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator): `internal/simulator`
- [Traffic Scenarios](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator): `internal/simulator`
- [Traffic Sender](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator): `internal/simulator`
- [Truth Writer](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/simulator): `internal/simulator`

### Decision Evaluation

- [Ground Truth](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/groundtruth/record.go): `internal/groundtruth/record.go`
- [Evaluator CLI](https://github.com/renan-lab/fraud-analysis-go/blob/main/cmd/evaluator/main.go): `cmd/evaluator/main.go`
- [Evaluation Service](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/evaluation/service.go): `internal/evaluation/service.go`
- [Quality Metrics](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/evaluation): `internal/evaluation`
- [Evaluation Report](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/evaluation/report.go): `internal/evaluation/report.go`

### Shared Infrastructure

- **Kafka**
- **Redis State**
- [Kafka Client](https://github.com/renan-lab/fraud-analysis-go/tree/main/internal/platform/kafka): `internal/platform/kafka`
- [Redis Client](https://github.com/renan-lab/fraud-analysis-go/blob/main/internal/platform/redis/client.go): `internal/platform/redis/client.go`

### Other components

- **Transaction Client**

## Connections

- Transaction Client → HTTP API: submits transactions (evidence: `README.md`)
- HTTP API → Request Handler: routes requests (evidence: `cmd/api/routes.go`)
- Request Handler → Ingest Service: ingests valid transactions (evidence: `internal/ingestion/handler.go`)
- Ingest Service → Received Event: constructs event (evidence: `internal/ingestion/service.go`)
- Ingest Service → Kafka: publishes event (evidence: `internal/ingestion/service.go`)
- HTTP API → Kafka Client: configures producer
- Analysis Worker → Kafka Client: configures consumer (evidence: `cmd/worker/main.go`)
- Analysis Worker → Redis Client: connects Redis (evidence: `cmd/worker/main.go`)
- Analysis Worker → Analysis Service: constructs service (evidence: `cmd/worker/main.go`)
- Analysis Worker → Event Consumer: wraps service (evidence: `cmd/worker/main.go`)
- Kafka → Event Consumer: delivers received events (evidence: `README.md`)
- Event Consumer → Analysis Service: handles event (evidence: `internal/analysis/consumer.go`)
- Analysis Service → Feature Store: loads and records features (evidence: `internal/analysis/service.go`)
- Analysis Service → Fraud Rules: evaluates rules (evidence: `internal/analysis/service.go`)
- Feature Store → Redis State: reads and writes state (evidence: `internal/analysis/featurestore_redis.go`)
- Analysis Service → Kafka: publishes decision (evidence: `README.md`)
- Analysis Service → Analyzed Event: constructs decision event (evidence: `internal/analysis/service.go`)
- Simulator CLI → Traffic Generator: creates generator (evidence: `cmd/simulator/main.go`)
- Simulator CLI → Traffic Sender: selects sender (evidence: `cmd/simulator/main.go`)
- Simulator CLI → Truth Writer: creates optional writer (evidence: `cmd/simulator/main.go`)
- Traffic Generator → Traffic Scenarios: generates scenario traffic
- Simulator CLI → Ground Truth: writes truth records (evidence: `README.md`)
- Traffic Sender → HTTP API: sends HTTP traffic (evidence: `README.md`)
- Evaluator CLI → Evaluation Service: runs evaluation (evidence: `cmd/evaluator/main.go`)
- Evaluator CLI → Ground Truth: loads truth (evidence: `cmd/evaluator/main.go`)
- Evaluator CLI → Kafka: reads analyzed events (evidence: `README.md`)
- Evaluation Service → Quality Metrics: computes quality metrics (evidence: `README.md`)
- Evaluation Service → Evaluation Report: returns report