Content
# Sentinel Fraud Detection Platform
Gercek zamanli e-ticaret fraud tespiti icin gelistirilmis, full-stack bir platform.
Islemler REST API uzerinden alinir, Kafka ile asenkron islenir, Redis destekli kural motorunda degerlendirilir, sonuc hem dashboard hem MCP araclari ile dis dunyaya acilir.
## Icerik
- [Proje Ozet](#proje-ozet)
- [Mimari ve Tech Stack](#mimari-ve-tech-stack)
- [Teknoloji Secimleri ve Gerekceleri](#teknoloji-secimleri-ve-gerekceleri)
- [Proje Dizin Yapisi](#proje-dizin-yapisi)
- [Hizli Baslangic Docker](#hizli-baslangic-docker)
- [Fraud Karar Mantigi 23 Rule](#fraud-karar-mantigi-23-rule)
- [Test ve Simulasyon](#test-ve-simulasyon)
- [API ve WebSocket Ozeti](#api-ve-websocket-ozeti)
- [MCP AI Ajan Entegrasyonu](#mcp-ai-ajan-entegrasyonu)
- [Lokal Gelistirme](#lokal-gelistirme)
- [Troubleshooting](#troubleshooting)
## Proje Ozet
Bu proje, sahtecilik supheli islemleri erken yakalamaya odaklanir:
- Canli transaction stream ve fraud alert paneli sunar
- Kullanici bazli risk durumu ve gecmis hareketleri raporlar
- AI ajanlarinin dogrudan sorgu yapabilmesi icin MCP toollari saglar
## Mimari ve Tech Stack
### Backend
- Java 21
- Spring Boot (REST API, Validation, WebSocket, Actuator)
- Spring Data JPA + Flyway
- Spring Kafka
- Spring Data Redis
- Spring AI MCP Server
### Frontend
- React + Vite + TypeScript
- Recharts, React Query, Zustand
- Nginx (container runtime)
### Altyapi
- Docker Compose
- PostgreSQL
- Redis
- Kafka + Zookeeper
### Veri Akisi
1. Client `POST /api/v1/transactions` ile islem yollar
2. Uygulama islemi kaydeder ve `transactions.raw` topic'ine publish eder
3. Consumer fraud kurallarini calistirir
4. Sonuc DB'ye yazilir (`APPROVED` veya `FRAUD`)
5. WebSocket ile `/topic/transactions` ve `/topic/fraud-alerts` guncellenir
6. MCP toollari fraud ve kullanici risk verisini AI istemcilerine sunar
## Teknoloji Secimleri ve Gerekceleri
- **Redis (Kural Motoru ve Cache Yonetimi):** Anomali ve fraud tespitinde (ozellikle velocity ve average amount kontrollerinde) gercek zamanli islem sayaclarini (counter) takip etmek elzemdir. Redis'in in-memory dogasi ve hizli okuma/yazma performansi, kullanici bazli risk profillerini hesaplarken karsilasilacak gecikmeleri minimuma indirmek icin tercih edilmistir.
- **Kafka (Asenkron isleme):** Gelen muazzam transaction akisini (event stream) kayipsiz ve darbogazsiz tamponlamak (buffering), ayrica fraud analizini ana uygulamadan decouple edip gecikmeleri onlemek adina secilmistir.
- **Java 21 & Spring Boot:** High-concurrency destegi (Virtual Threads), kurumsal seviyedeki olceklenebilirligi ve MCP araclari gibi AI bilesenlerini moduler bicimde sisteme entegre edebilme yetenegi nedenleriyle kullanilmistir.
- **React & WebSocket:** Surekli akan anlik islem loglarini ve fraud alarmlarini kullanicinin (analistin) karsisinda sayfayi yenilemeden (real-time) reaktif bir sekilde gosterebilmek amaciyla secilmistir.
## Proje Dizin Yapisi
Asagidaki yapi, repository'deki ana klasorleri ve kritik dosyalari ozetler:
```text
sentinel-fraud-detection/
|-- docker-compose.yml
|-- Dockerfile
|-- pom.xml
|-- README.md
|-- .env.example
|-- manual-input.sh
|-- auto-test.sh
|-- src/
| |-- main/
| | |-- java/com/furkanerd/sentinel_fraud_detection/
| | | |-- transaction/
| | | |-- fraud/
| | | |-- kafka/
| | | |-- websocket/
| | | |-- mcp/
| | | `-- user/
| | `-- resources/
| | |-- application.yml
| | `-- db/migration/
| `-- test/
|-- frontend/
| |-- Dockerfile
| |-- package.json
| |-- src/
| | |-- api/
| | |-- components/
| | |-- hooks/
| | |-- pages/
| | |-- store/
| | |-- types/
| | `-- utils/
| `-- public/
`-- script/
|-- transaction_simulator.py
|-- mcp_server.py
`-- README.md
```
## Hizli Baslangic Docker
### Cevre Degiskenleri (Environment Variables)
Proje, inceleyenlerin hizlica derleyip calistirabilmesi amaciyla hazir degerler iceren `.env.example` dosyasiyla gelmektedir. Ayrica backend ve frontend uygulamalarinin calisabilmesi ve birbirine baglanabilmesi icin `.env` kurulumu gereklidir. Gerekli dosyalari olusturmak icin asagidaki adimi takip edebilirsiniz:
**Linux / macOS:**
```bash
cp .env.example .env
cp frontend/.env.example frontend/.env.local
```
**Windows (PowerShell):**
```powershell
Copy-Item .env.example -Destination .env
Copy-Item frontend/.env.example -Destination frontend/.env.local
```
### Konteynerleri Baslatma
Sistemde Docker ve Docker Compose kurulu olmalidir. Proje dizininde asagidaki komutu calistirin:
```bash
docker-compose up -d --build
```
Servisler:
- Frontend: `http://localhost:5173`
- Backend API: `http://localhost:8081`
- Swagger UI: `http://localhost:8081/swagger-ui.html`
- Health: `http://localhost:8081/actuator/health`
Sistemi durdur:
```bash
docker compose down
```
## Fraud Karar Mantigi 2/3 Rule
Bir islemde su 3 kuraldan en az 2'si ihlal edilirse islem fraud kabul edilir:
- Velocity: son 60 saniyede 5'ten fazla islem
- Amount: son 24 saat ortalamasinin 3 katindan buyuk tutar
- Location: fiziksel olarak imkansiz lokasyon gecisi
Seviyeleme:
- 0-1 ihlal -> LOW
- 2 ihlal -> MEDIUM (fraud)
- 3 ihlal -> HIGH (fraud)
## Test ve Simulasyon
### Manuel test
```bash
./manual-input.sh 11111111-1111-1111-1111-111111111111 450.75 Istanbul
```
### Otomatik trafik ve anomaly enjeksiyonu
```bash
./auto-test.sh --duration=60 --rate=8 --anomaly-chance=35
```
### Dry-run payload kontrolu
```bash
./auto-test.sh --duration=10 --rate=2 --anomaly-chance=25 --dry-run
```
### Python simulator senaryolari
```bash
python script/transaction_simulator.py --scenario all
python script/transaction_simulator.py --scenario velocity --velocity-count 10 --velocity-window 1
python script/transaction_simulator.py --scenario amount --amount-baseline-count 8 --amount-spike 50000
```
## API ve WebSocket Ozeti
### Transaction API
- `POST /api/v1/transactions`
- `GET /api/v1/transactions/users/{userId}`
- `GET /api/v1/transactions/fraud?from=...&to=...`
- `GET /api/v1/transactions/{transactionId}`
### User API
- `GET /api/v1/users/{userId}/status`
### Dokumantasyon
- Swagger: `http://localhost:8081/swagger-ui.html`
- OpenAPI: `http://localhost:8081/v3/api-docs`
### WebSocket
- Endpoint: `ws://localhost:8081/ws` (SockJS/STOMP)
- Topicler:
- `/topic/transactions`
- `/topic/fraud-alerts`
## MCP AI Ajan Entegrasyonu
Bu projede MCP araclari backend tarafinda tanimlidir:
- `get_recent_frauds`
- `check_user_status`
Kaynaklar:
- `src/main/java/com/furkanerd/sentinel_fraud_detection/mcp/McpToolsConfig.java`
- `src/main/resources/application.yml`
Ornek MCP istemci ayari:
```json
{
"mcpServers": {
"sentinel-fraud": {
"url": "http://localhost:8081/mcp"
}
}
}
```
Ornek promptlar:
- `Son 30 dakikadaki fraud islemlerini getir.`
- `11111111-1111-1111-1111-111111111111 kullanicisinin risk durumunu kontrol et.`
## Lokal Gelistirme
Docker disinda calismak istersen:
Backend:
```bash
./mvnw spring-boot:run
```
Frontend:
```bash
cd frontend
npm install
npm run dev
```
## Troubleshooting
- Port cakismasi: `8081`, `5173`, `5432`, `6379`, `9092`, `2181` dolu olabilir
- Frontend API baglanamiyor: `frontend/src/config.ts` ve `VITE_API_BASE_URL` degerini kontrol et
- Kafka baglantisi: container icinde `kafka:9092`, host tarafinda `localhost:29092` kullanimi proje ayarina gore degisebilir
- MCP baglantisi: uygulama ayakta mi, MCP URL istemci ayariyla eslesiyor mu kontrol et
## İletişim
- Linkedin : [Furkan Erdoğan](https://www.linkedin.com/in/furkanerd1/)
- Github : [@furkanerd1](https://github.com/furkanerd1)
- Email : furkanerdd1@gmail.com
---
Bu README, repository'deki mevcut dosya yapisi ve konfigurasyonlar baz alinarak hazirlanmistir.
