Transaction Fraud Detection Avro Schemas

Overview

This library provides comprehensive Avro schemas for the codedx-transfraud real-time fraud detection system built with Apache Flink. The schemas define the data contracts for financial transactions, fraud alerts, and processed outputs, enabling type-safe data streaming and interoperability across system components.

Schema Catalog

1. CardTransaction (card_transaction.avsc)

Core schema representing financial card transactions with comprehensive metadata.

Key Fields:

• transactionId: Unique transaction identifier
• cardId/customerId: Entity identifiers
• transactionAmount: Monetary amount with currency
• merchantInfo: Merchant details including location and category
• transactionType: POS, ONLINE, ATM, CONTACTLESS, RECURRING
• deviceInfo: Device metadata for digital transactions

2. FraudAlert (fraud_alert.avsc)

Schema for fraud detection alerts generated by the AI model.

Key Fields:

• alertId: Unique alert identifier
• fraudScore: AI model probability (0.0-1.0)
• severity: LOW, MEDIUM, HIGH, CRITICAL
• alertType: Pattern type (AMOUNT_ANOMALY, LOCATION_ANOMALY, etc.)
• recommendedAction: ALLOW, REVIEW, BLOCK_CARD, etc.
• riskFactors: Contributing risk factors

3. ProcessedTransaction (processed_transaction.avsc)

Schema for transaction outputs after feature engineering and model inference.

Key Fields:

• fraudProbability: Final fraud probability score
• status: APPROVED, REJECTED, FLAGGED_FOR_REVIEW
• featureVector: Engineered features for model inference
• windowedFeatures: Temporal aggregation features
• modelMetadata: AI model version and performance data

4. CustomerProfile (customer_profile.avsc)

Schema for customer behavioral profiles used in feature engineering.

Key Fields:

• typicalTransactionHours: Behavioral patterns
• frequentMerchants: Merchant preferences
• transactionVelocity: Historical transaction rates
• homeLocation: Geographic reference point

Installation

Maven

<dependency>
    <groupId>com.codedstream</groupId>
    <artifactId>codedx-transaction-fraud-library</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Gradle

implementation 'com.codedx.transfraud:avro-schemas:1.0-SNAPSHOT'

Usage Examples

Generating Java Classes

java -jar avro-tools-1.0-SNAPSHOT.jar compile schema \
    src/main/avro/ \
    src/main/java/

Flink Stream Processing

// Consume transactions from Kafka
DataStream<CardTransaction> transactions = env
    .addSource(new FlinkKafkaConsumer<>(
        "transactions-topic",
        ConfluentRegistryAvroDeserializationSchema.forSpecific(
            CardTransaction.class, 
            "http://schema-registry:8081"
        ),
        properties
    ));

// Produce fraud alerts
alerts.addSink(new FlinkKafkaProducer<>(
    "fraud-alerts-topic",
    ConfluentRegistryAvroSerializationSchema.forSpecific(
        FraudAlert.class,
        "fraud-alerts-topic-value",
        "http://schema-registry:8081"
    ),
    properties
));

Schema Evolution

All schemas are designed with forward and backward compatibility:

• Optional fields use ["null", "type"] unions with defaults
• New fields can be added with default values
• Enum symbols can be added (but not removed)

Development

Prerequisites

• Apache Avro 1.11+
• Java 8 or higher
• Maven 3.6+

Building

mvn clean compile
mvn package

Code Generation

mvn generate-sources

Schema Registry Integration

These schemas are compatible with Confluent Schema Registry:

// Register schemas
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data @src/main/avro/CardTransaction.avsc \
  http://localhost:8081/subjects/transactions-value/versions

Data Flow

CardTransaction (Input)
        ↓
Feature Engineering
        ↓
ProcessedTransaction (Intermediate)
        ↓
AI Model Inference
        ↓
FraudAlert (Output)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For support and questions:

• Create an issue in the repository
• Contact: nestorabiawuh@gmail.com
• LinkedIn: Nestor Martourez

Acknowledgments

• Apache Avro community
• Apache Flink community
• Financial industry best practices for fraud detection data models

Author

Nestor Martourez

• Email: nestorabiawuh@gmail.com
• LinkedIn: https://www.linkedin.com/in/nestor-abiangang/