# md-zakiur-rahman/atlas architecture

> Architecture diagram of the GitHub repository md-zakiur-rahman/atlas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/md-zakiur-rahman/atlas
- Repository: https://github.com/md-zakiur-rahman/atlas

## Overview

ATLAS is a Windows-focused defensive monitoring desktop application. In normal mode, the launcher starts host monitors and analysis services, which feed telemetry through the event bus for rule, risk, and ML assessment; detections can drive containment and alerts, while results appear in the analyst dashboard and persistence layer. Separate user-facing branches cover password/MFA and optional passkeys, vault encryption, and incident reporting. The README documents these capabilities and the high-level flow; unsampled modules are represented at their supported directory or file paths, without asserting their internal wiring.

Main entry points: [`monitor/event_bus.py`](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/event_bus.py) (Event Bus), [`dashboard/app.py`](https://github.com/md-zakiur-rahman/atlas/blob/main/dashboard/app.py) (Analyst Dashboard), [`main.py`](https://github.com/md-zakiur-rahman/atlas/blob/main/main.py) (Runtime Launcher), [`monitor/threat_engine.py`](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/threat_engine.py) (Threat Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Monitoring Runtime"]
  node_launcher["Runtime Launcher<br/>[main.py]"]
  node_filemon["File Monitor<br/>[file_monitor.py]"]
  node_procmon["Process Monitor<br/>[process_monitor.py]"]
  node_networkmon["Network Monitor<br/>[network_monitor.py]"]
  node_usbmon["USB Monitor<br/>[usb_monitor.py]"]
  node_bus["Event Bus<br/>[event_bus.py]"]
end

subgraph group_analysis["Threat Analysis"]
  node_features["Feature Extraction"]
  node_rules["Detection Rules<br/>[rules.py]"]
  node_risk["Risk Scoring<br/>[risk_engine.py]"]
  node_ml["Anomaly Detection<br/>[ml_detector.py]"]
  node_threat["Threat Engine<br/>[threat_engine.py]"]
end

subgraph group_response["Response and State"]
  node_response_engine["Automated Response<br/>[response_engine.py]"]
  node_alerts["Alert Delivery<br/>[alert_manager.py]"]
  node_state["Runtime State<br/>[runtime_state.py]"]
  node_database[("Persistence<br/>[db_manager.py]")]
end

subgraph group_identity["Identity and Vault"]
  node_auth["Password and OTP<br/>[otp_manager.py]"]
  node_passkeys["Passkey Pairing"]
  node_crypto["Encryption Service<br/>[crypto_service.py]"]
  node_vault["Vault<br/>[vault.py]"]
  node_email["Email Delivery<br/>[email_sender.py]"]
end

subgraph group_interface["API and Analyst UI"]
  node_dashboard["Analyst Dashboard<br/>[app.py]"]
  node_reports["Reports and Views<br/>[report_tab.py]"]
  node_api["Flask API<br/>[flask_app.py]"]
end

node_analyst(("Analyst"))
node_host(("Monitored Host"))
node_supabase[("Supabase")]
node_user(("User"))
node_email_service["Email Provider"]

node_launcher -->|"starts"| node_filemon
node_launcher -->|"starts"| node_procmon
node_launcher -->|"starts"| node_networkmon
node_launcher -->|"starts"| node_usbmon
node_filemon -.->|"publishes telemetry"| node_bus
node_procmon -.->|"publishes telemetry"| node_bus
node_networkmon -->|"publishes telemetry"| node_bus
node_usbmon -.->|"publishes telemetry"| node_bus
node_bus -->|"dispatches events"| node_threat
node_bus -->|"feeds features"| node_features
node_bus -->|"feeds scoring"| node_risk
node_threat -->|"evaluates"| node_rules
node_threat -->|"dispatches alerts"| node_alerts
node_features -->|"extracts baseline"| node_ml
node_ml -.->|"publishes anomalies"| node_bus
node_threat -->|"triggers response"| node_response_engine
node_response_engine -->|"updates containment"| node_state
node_response_engine -->|"locks vault"| node_vault
node_response_engine -->|"sends alerts"| node_email
node_alerts -.->|"records alerts"| node_state
node_bus -.->|"logs events"| node_database
node_database -->|"persists records"| node_supabase
node_analyst -->|"uses"| node_dashboard
node_dashboard -->|"reads runtime state"| node_state
node_dashboard -->|"opens views"| node_reports
node_dashboard -->|"requests encryption"| node_crypto
node_crypto -->|"delegates vault operations"| node_vault
node_analyst -->|"uses authentication"| node_api
node_api -->|"routes MFA"| node_auth
node_api -->|"routes passkeys"| node_passkeys
node_api -->|"requests remote lock"| node_vault
node_auth -->|"sends OTP"| node_email_service
node_email -->|"delivers notifications"| node_email_service
node_user -->|"signs in"| node_dashboard
node_host -->|"provides activity"| node_filemon
node_host -->|"provides activity"| node_procmon
node_host -->|"provides activity"| node_networkmon
node_host -->|"provides activity"| node_usbmon

click node_launcher "https://github.com/md-zakiur-rahman/atlas/blob/main/main.py"
click node_filemon "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/file_monitor.py"
click node_procmon "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/process_monitor.py"
click node_networkmon "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/network_monitor.py"
click node_usbmon "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/usb_monitor.py"
click node_bus "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/event_bus.py"
click node_features "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/feature_extractor.py"
click node_rules "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/rules.py"
click node_risk "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/risk_engine.py"
click node_ml "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/ml_detector.py"
click node_threat "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/threat_engine.py"
click node_response_engine "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/response_engine.py"
click node_alerts "https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/alert_manager.py"
click node_state "https://github.com/md-zakiur-rahman/atlas/blob/main/core/runtime_state.py"
click node_database "https://github.com/md-zakiur-rahman/atlas/blob/main/database/db_manager.py"
click node_dashboard "https://github.com/md-zakiur-rahman/atlas/blob/main/dashboard/app.py"
click node_reports "https://github.com/md-zakiur-rahman/atlas/blob/main/dashboard/report_tab.py"
click node_api "https://github.com/md-zakiur-rahman/atlas/blob/main/api/flask_app.py"
click node_auth "https://github.com/md-zakiur-rahman/atlas/blob/main/auth/otp_manager.py"
click node_passkeys "https://github.com/md-zakiur-rahman/atlas/blob/main/auth/biometric_manager.py"
click node_crypto "https://github.com/md-zakiur-rahman/atlas/blob/main/core/crypto_service.py"
click node_vault "https://github.com/md-zakiur-rahman/atlas/blob/main/core/vault.py"
click node_email "https://github.com/md-zakiur-rahman/atlas/blob/main/notifications/email_sender.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_filemon,node_procmon,node_networkmon,node_usbmon,node_bus,node_user toneBlue
class node_features,node_rules,node_risk,node_ml,node_threat,node_supabase toneAmber
class node_response_engine,node_alerts,node_state,node_database toneMint
class node_auth,node_passkeys,node_crypto,node_vault,node_email toneRose
class node_dashboard,node_reports,node_api,node_analyst,node_host,node_email_service toneIndigo
```

## Components

### Monitoring Runtime

- [Runtime Launcher](https://github.com/md-zakiur-rahman/atlas/blob/main/main.py): `main.py`
- [File Monitor](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/file_monitor.py): `monitor/file_monitor.py`
- [Process Monitor](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/process_monitor.py): `monitor/process_monitor.py`
- [Network Monitor](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/network_monitor.py): `monitor/network_monitor.py`
- [USB Monitor](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/usb_monitor.py): `monitor/usb_monitor.py`
- [Event Bus](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/event_bus.py): `monitor/event_bus.py`

### Threat Analysis

- [Feature Extraction](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/feature_extractor.py): `monitor/feature_extractor.py`
- [Detection Rules](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/rules.py): `monitor/rules.py`
- [Risk Scoring](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/risk_engine.py): `monitor/risk_engine.py`
- [Anomaly Detection](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/ml_detector.py): `monitor/ml_detector.py`
- [Threat Engine](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/threat_engine.py): `monitor/threat_engine.py`

### Response and State

- [Automated Response](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/response_engine.py): `monitor/response_engine.py`
- [Alert Delivery](https://github.com/md-zakiur-rahman/atlas/blob/main/monitor/alert_manager.py): `monitor/alert_manager.py`
- [Runtime State](https://github.com/md-zakiur-rahman/atlas/blob/main/core/runtime_state.py): `core/runtime_state.py`
- [Persistence](https://github.com/md-zakiur-rahman/atlas/blob/main/database/db_manager.py): `database/db_manager.py`

### Identity and Vault

- [Password and OTP](https://github.com/md-zakiur-rahman/atlas/blob/main/auth/otp_manager.py): `auth/otp_manager.py`
- [Passkey Pairing](https://github.com/md-zakiur-rahman/atlas/blob/main/auth/biometric_manager.py): `auth/biometric_manager.py`
- [Encryption Service](https://github.com/md-zakiur-rahman/atlas/blob/main/core/crypto_service.py): `core/crypto_service.py`
- [Vault](https://github.com/md-zakiur-rahman/atlas/blob/main/core/vault.py): `core/vault.py`
- [Email Delivery](https://github.com/md-zakiur-rahman/atlas/blob/main/notifications/email_sender.py): `notifications/email_sender.py`

### API and Analyst UI

- [Analyst Dashboard](https://github.com/md-zakiur-rahman/atlas/blob/main/dashboard/app.py): `dashboard/app.py`
- [Reports and Views](https://github.com/md-zakiur-rahman/atlas/blob/main/dashboard/report_tab.py): `dashboard/report_tab.py`
- [Flask API](https://github.com/md-zakiur-rahman/atlas/blob/main/api/flask_app.py): `api/flask_app.py`

### Other components

- **Analyst**
- **Monitored Host**
- **Supabase**
- **User**
- **Email Provider**

## Connections

- Runtime Launcher → File Monitor: starts (evidence: `main.py`)
- Runtime Launcher → Process Monitor: starts (evidence: `main.py`)
- Runtime Launcher → Network Monitor: starts (evidence: `main.py`)
- Runtime Launcher → USB Monitor: starts (evidence: `main.py`)
- File Monitor → Event Bus: publishes telemetry
- Process Monitor → Event Bus: publishes telemetry
- Network Monitor → Event Bus: publishes telemetry (evidence: `monitor/network_monitor.py`)
- USB Monitor → Event Bus: publishes telemetry
- Event Bus → Threat Engine: dispatches events (evidence: `monitor/threat_engine.py`)
- Event Bus → Feature Extraction: feeds features
- Event Bus → Risk Scoring: feeds scoring (evidence: `monitor/risk_engine.py`)
- Threat Engine → Detection Rules: evaluates (evidence: `monitor/threat_engine.py`)
- Threat Engine → Alert Delivery: dispatches alerts (evidence: `monitor/threat_engine.py`)
- Feature Extraction → Anomaly Detection: extracts baseline
- Anomaly Detection → Event Bus: publishes anomalies
- Threat Engine → Automated Response: triggers response
- Automated Response → Runtime State: updates containment (evidence: `monitor/response_engine.py`)
- Automated Response → Vault: locks vault (evidence: `monitor/response_engine.py`)
- Automated Response → Email Delivery: sends alerts (evidence: `monitor/response_engine.py`)
- Alert Delivery → Runtime State: records alerts
- Event Bus → Persistence: logs events (evidence: `database/db_manager.py`)
- Persistence → Supabase: persists records
- Analyst → Analyst Dashboard: uses
- Analyst Dashboard → Runtime State: reads runtime state (evidence: `dashboard/app.py`)
- Analyst Dashboard → Reports and Views: opens views (evidence: `dashboard/app.py`)
- Analyst Dashboard → Encryption Service: requests encryption
- Encryption Service → Vault: delegates vault operations (evidence: `core/crypto_service.py`)
- Analyst → Flask API: uses authentication
- Flask API → Password and OTP: routes MFA (evidence: `api/flask_app.py`)
- Flask API → Passkey Pairing: routes passkeys (evidence: `api/flask_app.py`)
- Flask API → Vault: requests remote lock
- Password and OTP → Email Provider: sends OTP
- Email Delivery → Email Provider: delivers notifications
- User → Analyst Dashboard: signs in
- Monitored Host → File Monitor: provides activity
- Monitored Host → Process Monitor: provides activity
- Monitored Host → Network Monitor: provides activity
- Monitored Host → USB Monitor: provides activity
