AlertIQ - AI-Powered Case Resolution System

A full-stack fintech case resolution system with multi-agent automation for fraud detection, dispute management, and automated actions with explainable traces and observability.

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   React     │─────▶│   Node API   │─────▶│  PostgreSQL │
│  Frontend   │◀─SSE─│   (Express)  │      │     +       │
│  (Vite)     │      │  Multi-Agent │      │    Redis    │
└─────────────┘      └──────────────┘      └─────────────┘
     │                      │
     │                      ├─ Orchestrator (Triage)
     │                      ├─ Risk Agent
     │                      ├─ Fraud Agent
     │                      ├─ KB Agent
     │                      ├─ Action Agent
     │                      └─ Redactor Agent
     │
     └─ Pages: Dashboard, Alerts, Customer Profile, Evaluations

Quick Start

# 1. Clone and setup
git clone https://github.com/ayusharma-ctrl/AlertIQ.git
cd AlertIQ

# 2. Start all services
docker compose up -d

# 3. Seed database (first time only)
docker compose exec api npm run seed

# 4. Access application
Frontend: http://localhost:3000
API: http://localhost:4000
Metrics: http://localhost:4000/metrics

Key Features

• Multi-Agent Triage: Orchestrated pipeline with fraud detection, risk scoring, and action recommendations
• Real-time Streaming: SSE-based live updates for triage progress
• Action Automation: Freeze cards, open disputes with OTP verification (OTP: 123456)
• Observability: Prometheus metrics, structured JSON logs, audit trails
• Security: PII redaction, rate limiting (5 req/sec), idempotency, CSP headers
• Performance: p95 < 100ms on 1M+ transactions with optimized indexes

Stack

• Frontend: React 18, TypeScript, Tailwind CSS, TanStack Virtual
• Backend: Node.js, Express, TypeScript, Prisma ORM
• Database: PostgreSQL 15, Redis 7
• Infra: Docker Compose

Trade-offs & Design Decisions

1. SSE over WebSockets: Simpler, works with HTTP/2, auto-reconnects, no bidirectional needed
2. Keyset pagination: Stable cursors for large datasets, better performance than offset
3. Circuit breakers: 30s open after 3 failures to prevent cascading failures
4. Deterministic fallbacks: System works offline without LLM dependencies
5. Virtual scrolling: Handle 2k+ rows without DOM bloat

API Examples

# Start triage
curl -X POST http://localhost:4000/api/v1/triage \
  -H "X-API-Key: test-api-key" \
  -H "Content-Type: application/json" \
  -d '{"alertId": "alert-123", "customerId": "cust-456"}'

# Freeze card with OTP
curl -X POST http://localhost:4000/api/v1/actions/freeze \
  -H "X-API-Key: test-api-key" \
  -H "Idempotency-Key: freeze-789" \
  -H "Content-Type: application/json" \
  -d '{"cardId": "card-123", "otp": "123456", "reason": "Suspicious activity"}'

# Get customer transactions (last 90 days)
curl "http://localhost:4000/api/v1/customers/cust-123/transactions?last=90d&limit=50" \
  -H "X-API-Key: test-api-key"

Monitoring & Observability

• Metrics: http://localhost:4000/metrics (Prometheus format)
• Health: http://localhost:4000/health
• Logs: docker compose logs -f api

Environment Variables

Create .env files in server/ and client/ directories:

server/.env:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/alertiq"
REDIS_URL="redis://localhost:6379"
PORT=4000
NODE_ENV=development
LOG_LEVEL=info
API_KEY=dev-api-key-12345
CORS_ORIGIN=http://localhost:3000
RUN_SEED=true
ENABLE_LLM=false

client/.env:

VITE_API_URL=http://localhost:4000

Troubleshooting

Port already in use

# Stop conflicting services
docker compose down
lsof -ti:3000 | xargs kill  # Frontend
lsof -ti:4000 | xargs kill  # API

Database connection errors

# Restart database
docker compose restart db
# Check logs
docker compose logs db

Frontend not loading

# Rebuild client
docker compose build client
docker compose up -d client

Security Features

• API Key Authentication: All endpoints require X-API-Key header
• Rate Limiting: Token bucket (5 req/sec per client)
• Idempotency: Mutation endpoints require Idempotency-Key
• PII Redaction: Automatic masking of PANs (13-19 digits) and emails
• CSP Headers: Content-Security-Policy prevents XSS
• OTP Verification: Card freeze requires valid OTP (demo: 123456)

Documentation

• Architecture Decisions - Design rationale and trade-offs
• API Collection - Complete Postman collection
• Evaluation Report - Test results and metrics