-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture
MailIntel AI follows a modular, layered architecture designed for maintainability, testability, and future extensibility.
The system separates user interface, business logic, intelligence modules, reporting, and workflows into independent components.
RFC822 Email (.eml)
│
▼
Email Parsing Engine
│
▼
Investigation Workflow
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
Authentication Language Intelligence URL Intelligence
│ │ │
└────────────────────┼────────────────────┘
▼
Evidence Collection
│
▼
Findings Engine
│
▼
Explainable Risk Engine
│
▼
Investigation Report
│ │
▼ ▼
JSON Report Executive PDF
│
▼
Streamlit Dashboard
The architecture follows several software engineering principles.
Each module has a single responsibility.
Examples:
- Email Parser only parses emails.
- Intelligence modules only analyze evidence.
- Reporting modules only generate reports.
- UI only presents investigation results.
This minimizes coupling between components.
The project is organized into logical layers.
Presentation Layer
│
Application Layer
│
Domain Logic
│
Infrastructure
Each layer depends only on abstractions below it.
Rather than generating opaque risk scores, MailIntel AI collects evidence first.
Every recommendation and risk score can be traced back to specific observations.
Example:
Finding:
Suspicious URL detected
Evidence:
http://login-security-update.example
Risk Contribution:
+20 points
This makes investigations transparent and auditable.
Responsible for:
- Reading RFC822 email files
- Extracting headers
- Extracting body content
- Producing structured email objects
Examines:
- SPF
- DKIM
- DMARC
Authentication failures increase investigation risk.
Extracts URLs from the email and performs:
- Domain extraction
- Suspicious URL detection
- Indicator collection
Future versions may integrate external threat intelligence.
Analyzes textual content for phishing characteristics.
Examples include:
- Urgency
- Credential requests
- Financial requests
- Social engineering language
Collects structured evidence generated by all intelligence modules.
Evidence becomes the foundation for investigation findings.
Converts evidence into human-readable findings.
Example:
High Risk
Multiple authentication failures detected.
Several suspicious URLs identified.
Language indicates credential harvesting attempt.
Calculates an explainable investigation score.
The score is derived from accumulated evidence rather than arbitrary weighting.
Generates:
- JSON Investigation Report
- Executive PDF Report
Both reports contain identical investigation results in different formats.
The Streamlit dashboard provides:
- Investigation Overview
- Risk Profile
- Evidence Explorer
- Language Analysis
- Investigation Reports
- PDF Download
- JSON Download
Email Upload
↓
Email Parsing
↓
Evidence Collection
↓
Intelligence Modules
↓
Findings Generation
↓
Risk Calculation
↓
Report Generation
↓
Dashboard
The architecture was chosen to achieve the following goals:
- Modular development
- Independent testing
- Easy future enhancements
- Explainable investigations
- Enterprise-ready structure
Each component can evolve independently without affecting unrelated parts of the system.
Planned architectural enhancements include:
- FastAPI backend
- React frontend
- PostgreSQL persistence
- User authentication
- Case management
- Threat intelligence APIs
- Multi-user investigations
- Background processing
- Batch email analysis
The current architecture was designed to support these future capabilities with minimal refactoring.