TrustTwin AI

Unified Document Anomaly Detection & Autonomous Regulatory Compliance for Banks

A full-stack web application prototype that merges real-time document anomaly detection with autonomous regulatory compliance workflows. Built with React, TypeScript, FastAPI, PostgreSQL/SQLite, and powered by 5 simulated AI agents.

---

🚀 Quick Start

Option 1: Run Locally (No Docker Required)

Prerequisites: Python 3.11+ and Node.js 18+

cd TrustTwin_AI

# One command to start everything:
chmod +x start-local.sh
./start-local.sh

This script will:

1. Create a Python virtual environment and install dependencies
2. Run database migrations (SQLite — no database install needed)
3. Seed 10 RBI/SEBI regulations
4. Start the backend on http://localhost:8000
5. Install npm packages and start the frontend on http://localhost:3000

To stop:

./stop-local.sh

Option 2: Run with Docker

Prerequisites: Docker and Docker Compose

cd TrustTwin_AI
docker compose up --build

Uses PostgreSQL with pgvector. App runs on http://localhost:3000.

---

🌐 Access Points

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000
API Documentation	http://localhost:8000/docs

---

🏗 Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │────▶│   Backend    │────▶│   Database   │
│  React + TS  │     │   FastAPI    │     │ SQLite/PG    │
│  Tailwind    │     │  5 AI Agents │     │              │
│  Port: 3000  │     │  Port: 8000  │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

🤖 Simulated AI Agents

#	Agent	Role
1	🔍 Document Sentinel	Scans uploaded documents, generates perceptual hashes, detects anomalies
2	📋 Regulatory Watchdog	Matches incidents with RBI/SEBI regulations via keyword analysis
3	⚖️ Legal Decoder	Generates Measurable Action Points (MAPs) from compliance templates
4	✅ Process Compliance	Assigns MAPs to departments, handles validation lifecycle
5	🔮 Digital Twin	Runs impact simulations estimating financial and reputational outcomes

---

📄 Features

Document Upload & Anomaly Detection

• Drag-and-drop PDF/image upload
• Perceptual hash comparison against reference documents
• Real-time forgery score with visual anomaly indicators
• Automatic incident creation for tampered documents

Regulatory Compliance Pipeline

• Automatic regulation matching from seeded RBI/SEBI rules
• Rule-based MAP generation with department assignment (Legal, Branch, IT, Compliance)
• Action point lifecycle: Pending → In Progress → Completed → Validated
• Auto-validation after 5-second delay
• Compliance certificate generation with digital signature

Digital Twin Sandbox

• Impact simulation with financial loss prevention estimates
• Reputational damage scoring (1-10 scale)
• Operational cost savings analysis
• Interactive Chart.js visualizations

Real-Time Dashboard

• Live activity feed (3-second polling)
• Aggregated statistics across all documents and incidents
• Recent incidents table with severity badges
• Agent status indicators

---

🗄 Database Schema

Table	Description
documents	Uploaded files with hash and anomaly status
incidents	Security incidents from anomaly detection
regulations	Seeded RBI/SEBI regulatory rules (10 entries)
incident_regulations	Many-to-many incident ↔ regulation links
action_points	Compliance tasks (MAPs) assigned to departments
simulation_results	Digital Twin simulation outputs
activity_log	Real-time agent activity feed

---

🔌 API Endpoints

Method	Endpoint	Description
POST	/api/upload	Upload & scan document
GET	/api/incidents	List all incidents
GET	/api/incidents/{id}	Incident details with MAPs, regulations, simulations
POST	/api/incidents/{id}/simulate	Run Digital Twin simulation
GET	/api/incidents/{id}/certificate	Get compliance certificate
POST	/api/action-points/{id}/complete	Mark MAP complete → auto-validates after 5s
GET	/api/dashboard/stats	Dashboard statistics
GET	/api/activity-log	Live activity feed
GET	/api/health	Health check

---

🎨 Design Theme

• Primary Colors: Dark navy (#0f172a) + Gold accents (#d4a843)
• Typography: Inter (Google Fonts)
• UI Pattern: Glassmorphism with backdrop blur
• Animations: Fade-in, slide-up, pulse, glow effects
• Layout: Responsive sidebar + main content area

---

🛠 Tech Stack

Frontend

• React 18 + TypeScript
• Vite (build tool)
• Tailwind CSS 3.4
• Chart.js + react-chartjs-2
• React Router v6
• React Dropzone
• Axios

Backend

• Python 3.11+
• FastAPI
• SQLAlchemy 2.0
• Alembic (migrations)
• Pillow + imagehash (perceptual hashing)
• Pydantic v2

Database

• Local: SQLite (zero-install)
• Docker: PostgreSQL 16 + pgvector

---

📁 Project Structure

TrustTwin_AI/
├── start-local.sh          # One-command local start
├── stop-local.sh           # Stop all services
├── docker-compose.yml      # Docker deployment
├── .env                    # Environment variables
├── README.md
│
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── alembic.ini
│   ├── alembic/
│   │   ├── env.py
│   │   └── versions/
│   │       └── 001_initial.py
│   ├── app/
│   │   ├── main.py         # FastAPI entry point
│   │   ├── config.py       # Settings
│   │   ├── database.py     # SQLAlchemy setup
│   │   ├── models.py       # ORM models
│   │   ├── schemas.py      # Pydantic schemas
│   │   ├── seed.py         # Regulation seed data
│   │   ├── agents/
│   │   │   ├── document_sentinel.py
│   │   │   ├── regulatory_watchdog.py
│   │   │   ├── legal_decoder.py
│   │   │   ├── process_compliance.py
│   │   │   └── digital_twin.py
│   │   └── routers/
│   │       ├── upload.py
│   │       ├── incidents.py
│   │       ├── dashboard.py
│   │       └── action_points.py
│   └── uploads/
│
└── frontend/
    ├── Dockerfile
    ├── nginx.conf
    ├── package.json
    ├── vite.config.ts
    ├── tailwind.config.js
    └── src/
        ├── App.tsx
        ├── api.ts
        ├── types.ts
        ├── index.css
        ├── components/
        │   ├── Layout.tsx
        │   ├── StatCard.tsx
        │   ├── IncidentTable.tsx
        │   ├── ActivityFeed.tsx
        │   ├── FileUpload.tsx
        │   ├── ForgeryResult.tsx
        │   ├── MAPTimeline.tsx
        │   ├── SimulationChart.tsx
        │   └── ComplianceCert.tsx
        └── pages/
            ├── Dashboard.tsx
            ├── Upload.tsx
            ├── IncidentList.tsx
            └── IncidentDetail.tsx

---

📝 License

This project is a prototype built for demonstration purposes.