Enterprise-grade financial fraud detection system that combines MongoDB Atlas vector search, Temporal workflows, and AWS Bedrock AI to demonstrate real-time transaction analysis and intelligent fraud detection capabilities.
# 1. Clone the repository
git clone https://github.com/mongodb-partners/maap-temporal-ai-agent-qs.git
cd maap-temporal-ai-agent-qs
# 2. Configure environment (minimal setup)
cp .env.example .env
# Edit .env with your MongoDB Atlas URI and AWS credentials
# 3. Run quick setup (creates venv, installs deps, starts Temporal on Docker and launch the app)
./scripts/quick_setup.sh
# or Run docker setup (Deploy everything on Docker and launch the app)
./scripts/docker_setup.sh- Overview
- Business Value & Use Cases
- Architecture
- Installation & Configuration
- Usage
- Evaluation Guide
- Troubleshooting
- Next Steps
- License
What It Does: Processes financial transactions through an AI-powered decision pipeline that combines rule-based evaluation, vector similarity search, and advanced fraud detection to provide real-time approve/reject decisions with detailed reasoning.
Business Value:
- ✅ Advanced fraud detection through hybrid AI + vector search approach
- ✅ Reduced operational costs via automated transaction processing
- ✅ Fast decision processing with asynchronous workflows
- ✅ Decreased manual review workload through AI-assisted decisions
- ✅ Complete audit trails with explainable AI reasoning
PoV Scope Limitations:
- Mock data for demonstration (no real financial data)
- Single-region deployment (production would be multi-region)
- Performance not optimized for high throughput
- Basic notification system
- Simplified compliance checks (production requires full KYC/AML)
- Fraud Ring Detection - Identifies coordinated criminal networks through graph traversal
- Real-time Risk Scoring - AI-powered analysis with confidence scoring
- Automated Compliance - Sanctions screening and regulatory checks
- Human-in-the-Loop - Escalation workflows for complex cases
- Cost Optimization - Reduces manual review while maintaining accuracy
| Metric | Description | PoV Demonstrates |
|---|---|---|
| Detection Capability | AI-powered analysis | Multi-factor risk assessment |
| Processing Speed | Workflow execution time | Asynchronous processing |
| Auto-Approval | Transactions approved without manual review | Confidence-based decisions |
| Manual Review | Human-in-the-loop capability | Queue management system |
| Audit Trail | Decision tracking | Complete workflow history |
- MongoDB Atlas Integration: Demonstrates vector search, ACID transactions, and aggregation pipelines
- AI Workflow Orchestration: Shows Temporal's reliability for mission-critical processes
- Cloud-Native Architecture: Ready for AWS/Azure/GCP deployment
- Regulatory Compliance: Built-in audit trails and explainability
graph LR
A[Transaction API] --> B[Temporal Workflow]
B --> C[MongoDB Atlas]
B --> D[AWS Bedrock AI]
C --> E[Vector Search]
C --> F[Graph Analysis]
D --> G[Fraud Detection]
G --> H{Decision}
H -->|Approved| I[Process Transaction]
H -->|Review| J[Human Queue]
H -->|Rejected| K[Block & Alert]
J --> L[Dashboard UI]
- FastAPI Backend - REST API for transaction submission
- Temporal Worker - Durable workflow execution engine
- MongoDB Atlas - Document store with vector search capabilities
- AWS Bedrock - Claude for analysis, Cohere for fallback embeddings
- Voyage AI - Finance-optimized embeddings (primary embedding provider)
- Streamlit Dashboard - Real-time monitoring and review interface
- MongoDB Atlas with 1024-dimensional vector indexes
- Temporal for workflow orchestration and retry logic
- AWS Bedrock API for AI inference
- RESTful APIs for external system integration
For detailed architecture documentation, see docs/ARCHITECTURE.md.
- Python 3.11+
- Docker & Docker Compose
- MongoDB Atlas account (free tier works)
- AWS account with Bedrock access
- 8GB RAM minimum
# Start all services with Docker Compose
docker-compose up -d
# Verify services are running
docker ps
curl http://localhost:8000/health# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Start Temporal (required)
cd docker-compose && docker-compose up -d && cd ..
# Initialize MongoDB
python -m scripts.setup_mongodb
# Start services (3 terminals needed)
python -m temporal.run_worker # Terminal 1: Worker
uvicorn api.main:app --reload # Terminal 2: API
streamlit run app.py # Terminal 3: Dashboard| Variable | Description | Default | Required |
|---|---|---|---|
MONGODB_URI |
MongoDB Atlas connection string | - | ✅ |
AWS_ACCESS_KEY_ID |
AWS credentials for Bedrock | - | ✅ |
AWS_SECRET_ACCESS_KEY |
AWS secret key | - | ✅ |
CONFIDENCE_THRESHOLD_APPROVE |
Min confidence for auto-approval | 85 | ❌ |
AUTO_APPROVAL_LIMIT |
Max amount for auto-approval | 50000 | ❌ |
TEMPORAL_HOST |
Temporal server address | localhost:7233 | ❌ |
For complete configuration options, see docs/CONFIGURATION.md.
The system includes a comprehensive Streamlit dashboard for monitoring and managing transactions:
Key Features:
- 📊 Real-time Metrics - Monitor transaction volume, processing time, and AI confidence
- 🔍 Hybrid Search Demo - Visualize how different search methods work together
- 🚀 Scenario Launcher - Run pre-configured fraud detection scenarios
- 👥 Human Review Queue - Manage transactions requiring manual review
- ⚙️ Active Workflows - Track processing status in real-time
For detailed UI instructions, see the UI Usage Guide.
# Submit a test transaction
curl -X 'POST' \
'http://localhost:8000/api/transaction' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"transaction_id": "2025092400001",
"transaction_type": "wire_transfer",
"amount": 100,
"currency": "USD",
"sender": {
"account_number": "ACC-12345",
"country": "US",
"name": "Sam Eagleton"
},
"recipient": {
"account_number": "ACC-67890",
"country": "UK",
"name": "Nigel Wadsworth"
},
"risk_flags": [],
"reference_number": "95027064"
}'Use the Scenario Launcher in the left sidebar to run pre-configured test cases:
Select "Fraud Ring Detection" and click "Run Scenario" to submit suspicious transactions.
Monitor the scenario execution and see AI decisions:
The system detects structuring patterns and escalates transactions for review.
Review escalated transactions with AI recommendations:
Make informed decisions based on AI analysis and transaction details.
# Submit high-value transaction requiring manager approval
python -m scripts.advanced_scenarios
# Monitor in dashboard: http://localhost:8501
# Transaction will appear in "Pending Manager Approval" queue-
Streamlit Dashboard: http://localhost:8501
- Real-time transaction status
- Decision distribution charts
- Human review queue
- Performance metrics
-
Temporal UI: http://localhost:8080
- Workflow execution history
- Activity retry details
- Signal/query interface
-
API Documentation: http://localhost:8000/docs
- Interactive API testing
- Schema definitions
- Response examples
-
Automated Approval Path
- Submit low-risk transaction (<$5000, domestic)
- Verify immediate approval
- Check audit trail creation
-
Fraud Detection
- Run velocity check scenario
- Observe AI reasoning in dashboard
- Validate similar transaction matching
-
Human Review Workflow
- Submit medium-confidence transaction
- Review in dashboard queue
- Approve/reject with comments
-
System Resilience
- Kill Temporal worker mid-transaction
- Restart worker
- Verify transaction completes successfully
- Test transactions processed successfully
- Fraud scenarios correctly identified (8/10 minimum)
- Human review queue updates in real-time
- Audit trail captures all decisions
- Vector search returns relevant similar transactions
- Manager escalation triggers for >$50K transactions
For detailed evaluation procedures, see docs/EVALUATION_GUIDE.md.
| Problem | Cause | Solution |
|---|---|---|
| MongoDB connection failed | Invalid URI or network issue | Verify Atlas URI, check IP whitelist |
| Bedrock timeout errors | Missing AWS credentials | Ensure AWS keys are in .env file |
| Worker not processing | Temporal not running | Run docker-compose up -d in docker-compose/ |
| Dashboard blank | API not accessible | Check API is running on port 8000 |
| Vector search no results | Missing index | Run python -m scripts.setup_mongodb |
For detailed troubleshooting, see docs/TROUBLESHOOTING.md.
Scaling Considerations:
- Deploy to Kubernetes for auto-scaling
- Implement multi-region MongoDB Atlas clusters
- Add a caching layer for performance
- Configure CDN for dashboard assets
Security Hardening:
- Enable MongoDB encryption at rest
- Implement OAuth2/SAML authentication
- Add rate limiting and DDoS protection
- Configure AWS PrivateLink for Bedrock
CI/CD Pipeline:
- GitHub Actions for automated testing
- Docker image registry with vulnerability scanning
- Blue-green deployment strategy
- Automated performance regression testing
Production Monitoring:
- DataDog/New Relic APM integration
- Custom CloudWatch metrics and alarms
- PagerDuty incident management
- Grafana dashboards for business KPIs
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Questions? Contact the Solution Architecture team or open an issue in this repository.
Ready to evaluate? Start with the Quick Start section above.
Note: This repository contains a reference implementation intended for educational and exploratory purposes only. It is not production-ready in its current form.
While the architecture and design patterns demonstrated here reflect best practices for building AI-Powered Transaction Processing System, the implementation may lack:
- Comprehensive test coverage
- Robust error handling and validation
- Security hardening and access controls
- Performance optimizations for scale
- Long-term support or upgrade guarantees
Use this as a foundation to guide your own production implementations, but ensure thorough validation and customization before deploying in real-world environments.
