# divya2842/ai-soc-investigation-agent architecture

> Architecture diagram of the GitHub repository divya2842/ai-soc-investigation-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/divya2842/ai-soc-investigation-agent
- Repository: https://github.com/divya2842/ai-soc-investigation-agent

## Overview

This is an AI-assisted SOC investigation platform. Analysts authenticate, review alerts or look up IOCs, then launch an investigation that gathers logs and evidence, extracts and enriches indicators, maps MITRE techniques, scores risk, and produces an AI-assisted summary and report. Response actions are recommendations for human review, not automatic remediation. The README documents the broad investigation stages; source-index references and excerpts support the shown internal calls, while unsampled route and service details are represented only at subsystem level.

Main entry points: [`backend/app/agents/investigation_graph.py`](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/agents/investigation_graph.py) (Investigation graph), [`backend/app/main.py`](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/investigations.py`](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/investigations.py) (Investigation API), [`frontend/src/App.tsx`](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Analyst interface"]
  node_web["React application<br/>[App.tsx]"]
  node_alert_views["Alert views<br/>[AlertDetail.tsx]"]
  node_ioc_view["IOC lookup<br/>[IocLookup.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_client["Auth client<br/>[auth.ts]"]
end

subgraph group_api["API and access"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_alert_api["Alert API<br/>[alerts.py]"]
  node_investigation_api["Investigation API<br/>[investigations.py]"]
  node_ioc_api["IOC API<br/>[iocs.py]"]
  node_auth_security["JWT security<br/>[auth.py]"]
end

subgraph group_investigation["Investigation analysis"]
  node_agent["Investigation graph"]
  node_ioc_extract["IOC extraction<br/>[extract.py]"]
  node_log_source["Log correlation<br/>[source.py]"]
  node_enrichment["IOC enrichment<br/>[router.py]"]
  node_mitre_attack["ATT&amp;CK mapping<br/>[attack.py]"]
  node_mitre_atlas["ATLAS mapping<br/>[atlas.py]"]
  node_risk["Risk analysis<br/>[score.py]"]
  node_rag["Evidence retrieval<br/>[retriever.py]"]
  node_llm["LLM analysis<br/>[groq_client.py]"]
end

subgraph group_data["Persistence and reporting"]
  node_report["Investigation reports<br/>[report_builder.py]"]
  node_database[("SOC database<br/>[session.py]")]
  node_audit[("Audit records<br/>[audit.py]")]
end

subgraph group_integrations["External services"]
  node_intel_provider["Threat-intel providers<br/>[external.py]"]
  node_groq_service["Groq"]
  node_email_service["Email delivery<br/>[emailservice.py]"]
end

node_analyst(("SOC analyst"))

node_analyst -->|"uses"| node_web
node_web -->|"routes to"| node_alert_views
node_web -->|"routes to"| node_ioc_view
node_alert_views -->|"requests data"| node_api_client
node_ioc_view -->|"requests data"| node_api_client
node_web -->|"logs out via"| node_auth_client
node_api_client -->|"calls REST API"| node_backend
node_auth_client -->|"calls auth API"| node_auth_api
node_backend -->|"mounts routes"| node_auth_api
node_backend -->|"mounts routes"| node_alert_api
node_backend -->|"mounts routes"| node_investigation_api
node_backend -->|"mounts routes"| node_ioc_api
node_backend -->|"protects routes"| node_auth_security
node_auth_api -->|"uses JWT"| node_auth_security
node_auth_api -->|"sends recovery email"| node_email_service
node_investigation_api -->|"runs investigation"| node_agent
node_investigation_api -->|"builds report"| node_report
node_investigation_api -->|"reads and writes"| node_database
node_investigation_api -->|"records activity"| node_audit
node_backend -->|"initializes"| node_database
node_agent -->|"extracts indicators"| node_ioc_extract
node_agent -->|"collects log evidence"| node_log_source
node_agent -->|"enriches indicators"| node_enrichment
node_agent -->|"maps techniques"| node_mitre_attack
node_agent -->|"maps AI threats"| node_mitre_atlas
node_agent -->|"scores evidence"| node_risk
node_agent -->|"retrieves context"| node_rag
node_agent -->|"requests summary"| node_llm
node_agent -->|"records events"| node_audit
node_enrichment -->|"queries providers"| node_intel_provider
node_llm -->|"generates analysis"| node_groq_service
node_agent -.->|"produces analyst report"| node_report
node_analyst -->|"reviews results"| node_report
node_analyst -->|"requests investigation"| node_investigation_api

click node_web "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/App.tsx"
click node_alert_views "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/pages/AlertDetail.tsx"
click node_ioc_view "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/pages/IocLookup.tsx"
click node_api_client "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/services/api.ts"
click node_auth_client "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/services/auth.ts"
click node_backend "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/auth.py"
click node_alert_api "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/alerts.py"
click node_investigation_api "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/investigations.py"
click node_ioc_api "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/iocs.py"
click node_auth_security "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/security/auth.py"
click node_agent "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/agents/investigation_graph.py"
click node_ioc_extract "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/ioc/extract.py"
click node_log_source "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/logs/source.py"
click node_enrichment "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/ioc/enrichment/router.py"
click node_mitre_attack "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/mitre/attack.py"
click node_mitre_atlas "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/mitre/atlas.py"
click node_risk "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/risk/score.py"
click node_rag "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/rag/retriever.py"
click node_llm "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/llm/groq_client.py"
click node_report "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/reporting/report_builder.py"
click node_database "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/database/session.py"
click node_audit "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/audit.py"
click node_intel_provider "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/ioc/enrichment/external.py"
click node_email_service "https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/emailservice.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_alert_views,node_ioc_view,node_api_client,node_auth_client toneBlue
class node_backend,node_auth_api,node_alert_api,node_investigation_api,node_ioc_api,node_auth_security toneAmber
class node_agent,node_ioc_extract,node_log_source,node_enrichment,node_mitre_attack,node_mitre_atlas,node_risk,node_rag,node_llm toneMint
class node_report,node_database,node_audit toneRose
class node_intel_provider,node_groq_service,node_email_service,node_analyst toneIndigo
```

## Components

### Analyst interface

- [React application](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Alert views](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/pages/AlertDetail.tsx): `frontend/src/pages/AlertDetail.tsx`
- [IOC lookup](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/pages/IocLookup.tsx): `frontend/src/pages/IocLookup.tsx`
- [API client](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Auth client](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/frontend/src/services/auth.ts): `frontend/src/services/auth.ts`

### API and access

- [FastAPI application](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Alert API](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/alerts.py): `backend/app/api/alerts.py`
- [Investigation API](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/investigations.py): `backend/app/api/investigations.py`
- [IOC API](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/api/iocs.py): `backend/app/api/iocs.py`
- [JWT security](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/security/auth.py): `backend/app/security/auth.py`

### Investigation analysis

- [Investigation graph](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/agents/investigation_graph.py): `backend/app/agents/investigation_graph.py`
- [IOC extraction](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/ioc/extract.py): `backend/app/services/ioc/extract.py`
- [Log correlation](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/logs/source.py): `backend/app/services/logs/source.py`
- [IOC enrichment](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/ioc/enrichment/router.py): `backend/app/services/ioc/enrichment/router.py`
- [ATT&CK mapping](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/mitre/attack.py): `backend/app/services/mitre/attack.py`
- [ATLAS mapping](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/mitre/atlas.py): `backend/app/services/mitre/atlas.py`
- [Risk analysis](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/risk/score.py): `backend/app/services/risk/score.py`
- [Evidence retrieval](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/rag/retriever.py): `backend/app/services/rag/retriever.py`
- [LLM analysis](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/llm/groq_client.py): `backend/app/services/llm/groq_client.py`

### Persistence and reporting

- [Investigation reports](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/reporting/report_builder.py): `backend/app/services/reporting/report_builder.py`
- [SOC database](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Audit records](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/audit.py): `backend/app/services/audit.py`

### External services

- [Threat-intel providers](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/ioc/enrichment/external.py): `backend/app/services/ioc/enrichment/external.py`
- **Groq**
- [Email delivery](https://github.com/divya2842/ai-soc-investigation-agent/blob/main/backend/app/services/emailservice.py): `backend/app/services/emailservice.py`

### Other components

- **SOC analyst**

## Connections

- SOC analyst → React application: uses
- React application → Alert views: routes to (evidence: `frontend/src/main.tsx`)
- React application → IOC lookup: routes to (evidence: `frontend/src/main.tsx`)
- Alert views → API client: requests data (evidence: `frontend/src/pages/AlertDetail.tsx`)
- IOC lookup → API client: requests data (evidence: `frontend/src/pages/IocLookup.tsx`)
- React application → Auth client: logs out via (evidence: `frontend/src/App.tsx`)
- API client → FastAPI application: calls REST API (evidence: `frontend/src/services/api.ts`)
- Auth client → Authentication API: calls auth API (evidence: `frontend/src/services/auth.ts`)
- FastAPI application → Authentication API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Alert API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Investigation API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → IOC API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → JWT security: protects routes (evidence: `backend/app/main.py`)
- Authentication API → JWT security: uses JWT (evidence: `backend/app/api/auth.py`)
- Authentication API → Email delivery: sends recovery email (evidence: `backend/app/api/auth.py`)
- Investigation API → Investigation graph: runs investigation (evidence: `backend/app/api/investigations.py`)
- Investigation API → Investigation reports: builds report (evidence: `backend/app/api/investigations.py`)
- Investigation API → SOC database: reads and writes (evidence: `backend/app/api/investigations.py`)
- Investigation API → Audit records: records activity (evidence: `backend/app/api/investigations.py`)
- FastAPI application → SOC database: initializes (evidence: `backend/app/main.py`)
- Investigation graph → IOC extraction: extracts indicators (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → Log correlation: collects log evidence (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → IOC enrichment: enriches indicators (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → ATT&CK mapping: maps techniques (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → ATLAS mapping: maps AI threats (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → Risk analysis: scores evidence (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → Evidence retrieval: retrieves context (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → LLM analysis: requests summary (evidence: `backend/app/agents/investigation_graph.py`)
- Investigation graph → Audit records: records events (evidence: `backend/app/agents/investigation_graph.py`)
- IOC enrichment → Threat-intel providers: queries providers (evidence: `backend/app/services/ioc/enrichment/router.py`)
- LLM analysis → Groq: generates analysis
- Investigation graph → Investigation reports: produces analyst report
- SOC analyst → Investigation reports: reviews results
- SOC analyst → Investigation API: requests investigation
