# mantraak/ai-powered-soc-incident-generation-and-investigation-platform architecture

> Architecture diagram of the GitHub repository mantraak/ai-powered-soc-incident-generation-and-investigation-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform
- Repository: https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform

## Overview

Romulus is a SOC incident-generation and analyst-training platform. Administrators create scenarios manually or from threat intelligence; the backend generates investigation material, which players investigate and submit for evaluation. A parallel daily threat-feed workflow turns ranked threats into labs. The graph also includes collaboration, AI assistance, MITRE ATT&CK, and SOC-tool integration capabilities documented in the README. Some backend services and endpoints were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`backend/app/api/v1/api.py`](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/api/v1/api.py) (REST API), [`backend/app/services/threat_intel/pipeline.py`](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/pipeline.py) (Threat pipeline), [`backend/app/services/generator_service.py`](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/generator_service.py) (Scenario generation), [`frontend/src/App.tsx`](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web application<br/>[App.tsx]"]
  node_auth["Role-based access<br/>[authContext.tsx]"]
end

subgraph group_scenario["Scenario authoring"]
  node_scenario_ui["Scenario portal<br/>[ScenarioPages.tsx]"]
  node_generator["Scenario generation"]
  node_ai["AI provider<br/>[ai_provider.py]"]
  node_mitre["MITRE ATT&amp;CK<br/>[mitre_service.py]"]
end

subgraph group_investigation["SOC investigation"]
  node_investigation_ui["Investigation portal"]
  node_evaluation["Answer evaluation"]
  node_collaboration["Collaborative labs<br/>[lab_groups.py]"]
  node_assistant["AI assistant"]
  node_tool_registry["SOC tool integrations<br/>[tool_registry.py]"]
end

subgraph group_threat["Threat intelligence"]
  node_threat_feed["Threat feed<br/>[news_service.py]"]
  node_pipeline_ui["Pipeline controls"]
  node_pipeline["Threat pipeline<br/>[pipeline.py]"]
  node_normalizer["Threat normalization<br/>[normalizer.py]"]
  node_lab_creator["Threat lab creation<br/>[lab_creator.py]"]
end

subgraph group_platform["Backend platform"]
  node_scenario_data[("Scenario records<br/>[scenario.py]")]
  node_api["REST API<br/>[api.py]"]
  node_database[("Application database<br/>[session.py]")]
  node_settings["Platform configuration<br/>[config.py]"]
end

node_admin(("Administrator"))
node_analyst(("Player analyst"))
node_soc_tools{{"External SOC tools"}}
node_news_service{{"Newsdata.io"}}

node_admin -->|"uses"| node_web
node_analyst -->|"investigates in"| node_web
node_web -->|"provides routes"| node_auth
node_web -->|"routes to"| node_scenario_ui
node_scenario_ui -->|"submits scenarios"| node_api
node_api -.->|"routes scenario requests"| node_generator
node_generator -->|"requests generation"| node_ai
node_generator -->|"validates techniques"| node_mitre
node_generator -->|"creates scenario data"| node_scenario_data
node_investigation_ui -->|"loads investigation"| node_api
node_api -.->|"routes answers"| node_evaluation
node_analyst -->|"collaborates in labs"| node_collaboration
node_investigation_ui -.->|"opens SOC tools"| node_tool_registry
node_tool_registry -.->|"integrates tools"| node_soc_tools
node_admin -->|"manages runs"| node_pipeline_ui
node_pipeline_ui -->|"requests pipeline data"| node_api
node_api -.->|"triggers pipeline"| node_pipeline
node_pipeline -->|"normalizes articles"| node_normalizer
node_pipeline -->|"creates threat labs"| node_lab_creator
node_pipeline -.->|"collects threat articles"| node_news_service
node_pipeline -->|"records generated labs"| node_scenario_data
node_api -.->|"serves persisted data"| node_database
node_api -.->|"routes assistant requests"| node_assistant
node_settings -->|"configures endpoints"| node_soc_tools
node_admin -->|"selects techniques"| node_mitre

click node_web "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/App.tsx"
click node_auth "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/store/authContext.tsx"
click node_scenario_ui "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/pages/admin/ScenarioPages.tsx"
click node_generator "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/generator_service.py"
click node_ai "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/ai_provider.py"
click node_mitre "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/mitre_service.py"
click node_scenario_data "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/models/scenario.py"
click node_investigation_ui "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/pages/player/LabInvestigationPage.tsx"
click node_evaluation "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/evaluators/answer_evaluator.py"
click node_collaboration "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/api/v1/endpoints/lab_groups.py"
click node_assistant "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/assistant_service.py"
click node_tool_registry "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/integrations/tool_registry.py"
click node_threat_feed "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/news_service.py"
click node_pipeline_ui "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/pages/admin/ThreatPipelinePage.tsx"
click node_pipeline "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/pipeline.py"
click node_normalizer "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/normalizer.py"
click node_lab_creator "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/lab_creator.py"
click node_api "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/api/v1/api.py"
click node_database "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/db/session.py"
click node_settings "https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/core/config.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_web,node_auth toneBlue
class node_scenario_ui,node_generator,node_ai,node_mitre toneAmber
class node_investigation_ui,node_evaluation,node_collaboration,node_assistant,node_tool_registry toneMint
class node_threat_feed,node_pipeline_ui,node_pipeline,node_normalizer,node_lab_creator toneRose
class node_scenario_data,node_api,node_database,node_settings,node_admin,node_analyst,node_soc_tools,node_news_service toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Role-based access](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/store/authContext.tsx): `frontend/src/store/authContext.tsx`

### Scenario authoring

- [Scenario portal](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/pages/admin/ScenarioPages.tsx): `frontend/src/pages/admin/ScenarioPages.tsx`
- [Scenario generation](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/generator_service.py): `backend/app/services/generator_service.py`
- [AI provider](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/ai_provider.py): `backend/app/services/ai_provider.py`
- [MITRE ATT&CK](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/mitre_service.py): `backend/app/services/mitre_service.py`

### SOC investigation

- [Investigation portal](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/pages/player/LabInvestigationPage.tsx): `frontend/src/pages/player/LabInvestigationPage.tsx`
- [Answer evaluation](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/evaluators/answer_evaluator.py): `backend/app/evaluators/answer_evaluator.py`
- [Collaborative labs](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/api/v1/endpoints/lab_groups.py): `backend/app/api/v1/endpoints/lab_groups.py`
- [AI assistant](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/assistant_service.py): `backend/app/services/assistant_service.py`
- [SOC tool integrations](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/integrations/tool_registry.py): `backend/app/integrations/tool_registry.py`

### Threat intelligence

- [Threat feed](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/news_service.py): `backend/app/services/news_service.py`
- [Pipeline controls](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/frontend/src/pages/admin/ThreatPipelinePage.tsx): `frontend/src/pages/admin/ThreatPipelinePage.tsx`
- [Threat pipeline](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/pipeline.py): `backend/app/services/threat_intel/pipeline.py`
- [Threat normalization](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/normalizer.py): `backend/app/services/threat_intel/normalizer.py`
- [Threat lab creation](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/services/threat_intel/lab_creator.py): `backend/app/services/threat_intel/lab_creator.py`

### Backend platform

- [Scenario records](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/models/scenario.py): `backend/app/models/scenario.py`
- [REST API](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/api/v1/api.py): `backend/app/api/v1/api.py`
- [Application database](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Platform configuration](https://github.com/mantraak/ai-powered-soc-incident-generation-and-investigation-platform/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Administrator**
- **Player analyst**
- **External SOC tools**
- **Newsdata.io**

## Connections

- Administrator → Web application: uses
- Player analyst → Web application: investigates in
- Web application → Role-based access: provides routes (evidence: `frontend/src/App.tsx`)
- Web application → Scenario portal: routes to (evidence: `frontend/src/App.tsx`)
- Scenario portal → REST API: submits scenarios (evidence: `frontend/src/pages/admin/ScenarioPages.tsx`)
- REST API → Scenario generation: routes scenario requests
- Scenario generation → AI provider: requests generation (evidence: `backend/app/services/generator_service.py`)
- Scenario generation → MITRE ATT&CK: validates techniques (evidence: `backend/app/services/generator_service.py`)
- Scenario generation → Scenario records: creates scenario data (evidence: `backend/app/services/generator_service.py`)
- Investigation portal → REST API: loads investigation (evidence: `frontend/src/pages/player/LabInvestigationPage.tsx`)
- REST API → Answer evaluation: routes answers
- Player analyst → Collaborative labs: collaborates in labs
- Investigation portal → SOC tool integrations: opens SOC tools
- SOC tool integrations → External SOC tools: integrates tools
- Administrator → Pipeline controls: manages runs
- Pipeline controls → REST API: requests pipeline data (evidence: `frontend/src/pages/admin/ThreatPipelinePage.tsx`)
- REST API → Threat pipeline: triggers pipeline
- Threat pipeline → Threat normalization: normalizes articles (evidence: `backend/app/services/threat_intel/pipeline.py`)
- Threat pipeline → Threat lab creation: creates threat labs (evidence: `backend/app/services/threat_intel/pipeline.py`)
- Threat pipeline → Newsdata.io: collects threat articles
- Threat pipeline → Scenario records: records generated labs (evidence: `backend/app/services/threat_intel/pipeline.py`)
- REST API → Application database: serves persisted data
- REST API → AI assistant: routes assistant requests
- Platform configuration → External SOC tools: configures endpoints (evidence: `backend/app/core/config.py`)
- Administrator → MITRE ATT&CK: selects techniques
