# beenuar/aisoc architecture

> Architecture diagram of the GitHub repository beenuar/aisoc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beenuar/aisoc
- Repository: https://github.com/beenuar/aisoc
- Video tour (about a minute): https://gitdiagram.com/beenuar/aisoc/video

## Overview

AiSOC is a self-hostable AI security operations center. Its central workflow takes pushed or polled security telemetry through normalization and Kafka, detection and alert fusion, then AI investigation with auditable reasoning; human approval gates response actions. Separate product branches provide threat-intelligence ingestion and historical hunting, while the web console exposes alerts, cases, detections, playbooks, compliance, and operational views. The README documents stages and capabilities beyond the sampled code; arrows for those stages reflect that documentation, not inspected implementations.

Main entry points: [`services/fusion/app/services/fusion_engine.py`](https://github.com/beenuar/aisoc/blob/main/services/fusion/app/services/fusion_engine.py) (Alert Fusion), [`plans/cyble-aisoc/platform/backend/app/agents/investigator.py`](https://github.com/beenuar/aisoc/blob/main/plans/cyble-aisoc/platform/backend/app/agents/investigator.py) (AI Investigation), [`apps/web/src/app/(responder)/responder/approvals/page.tsx`](https://github.com/beenuar/aisoc/blob/main/apps/web/src/app/(responder)/responder/approvals/page.tsx) (Human Approval), [`apps/web/src/lib/api.ts`](https://github.com/beenuar/aisoc/blob/main/apps/web/src/lib/api.ts) (Web API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry Intake"]
  node_connector["Connector Polling<br/>[ingest_client.py]"]
  node_ingest_api["Ingest And Normalize"]
  node_kafka["Event Kafka"]
end

subgraph group_detect["Detection And Triage"]
  node_detections["Detection Rules<br/>[rule_engine.py]"]
  node_fusion["Alert Fusion<br/>[fusion_engine.py]"]
  node_alert_store[("Alert And Incident Data")]
end

subgraph group_response["Investigation And Response"]
  node_investigator["AI Investigation<br/>[investigator.py]"]
  node_ledger[("Investigation Ledger")]
  node_approval["Human Approval<br/>[page.tsx]"]
  node_playbooks["Playbook Execution<br/>[engine.py]"]
  node_response_services["Response Integrations"]
end

subgraph group_intel["Threat Intelligence"]
  node_threat_feed(("Threat Feeds"))
  node_intel_pipeline["IOC Processing<br/>[pipeline.py]"]
  node_intel_stores[("Intel Indexes")]
  node_hunt_engine["Threat Hunting<br/>[engine.py]"]
end

subgraph group_console["SOC Console"]
  node_web_console["Web SOC Console<br/>[page.tsx]"]
  node_mobile_responder["Mobile Responder<br/>[index.tsx]"]
  node_api_client["Web API Client<br/>[api.ts]"]
  node_replay["Case Replay"]
end

node_producer(("Security Tools"))
node_human(("SOC Analyst"))

node_producer -->|"pushes events"| node_ingest_api
node_producer -->|"provides telemetry"| node_connector
node_connector -->|"forwards normalized events"| node_ingest_api
node_ingest_api -->|"queues events"| node_kafka
node_kafka -->|"carries events"| node_detections
node_detections -->|"produces matches"| node_fusion
node_fusion -->|"records alerts"| node_alert_store
node_fusion -->|"triggers investigation"| node_investigator
node_investigator -->|"records reasoning"| node_ledger
node_investigator -->|"proposes response"| node_approval
node_human -->|"reviews actions"| node_approval
node_approval -->|"authorizes execution"| node_playbooks
node_playbooks -->|"runs response steps"| node_response_services
node_threat_feed -->|"supplies indicators"| node_intel_pipeline
node_intel_pipeline -->|"indexes indicators"| node_intel_stores
node_intel_stores -.->|"provides intel"| node_hunt_engine
node_web_console -->|"uses API client"| node_api_client
node_mobile_responder -.->|"uses API client"| node_api_client
node_api_client -->|"reads SOC data"| node_alert_store
node_human -->|"operates console"| node_web_console
node_human -->|"triages incidents"| node_mobile_responder
node_replay -->|"replays events"| node_ledger

click node_connector "https://github.com/beenuar/aisoc/blob/main/services/connectors/app/ingest_client.py"
click node_detections "https://github.com/beenuar/aisoc/blob/main/services/api/app/services/rule_engine.py"
click node_fusion "https://github.com/beenuar/aisoc/blob/main/services/fusion/app/services/fusion_engine.py"
click node_investigator "https://github.com/beenuar/aisoc/blob/main/plans/cyble-aisoc/platform/backend/app/agents/investigator.py"
click node_approval "https://github.com/beenuar/aisoc/blob/main/apps/web/src/app/(responder)/responder/approvals/page.tsx"
click node_playbooks "https://github.com/beenuar/aisoc/blob/main/services/agents/app/playbook/engine.py"
click node_intel_pipeline "https://github.com/beenuar/aisoc/blob/main/services/threatintel/app/feeds/pipeline.py"
click node_hunt_engine "https://github.com/beenuar/aisoc/blob/main/services/agents/app/hunt/engine.py"
click node_web_console "https://github.com/beenuar/aisoc/blob/main/apps/web/src/app/(app)/dashboard/page.tsx"
click node_mobile_responder "https://github.com/beenuar/aisoc/blob/main/apps/mobile/app/index.tsx"
click node_api_client "https://github.com/beenuar/aisoc/blob/main/apps/web/src/lib/api.ts"
click node_replay "https://github.com/beenuar/aisoc/blob/main/apps/web/src/components/cases/replay/useReplayController.ts"

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_connector,node_ingest_api,node_kafka toneBlue
class node_detections,node_fusion,node_alert_store toneAmber
class node_investigator,node_ledger,node_approval,node_playbooks,node_response_services toneMint
class node_threat_feed,node_intel_pipeline,node_intel_stores,node_hunt_engine toneRose
class node_web_console,node_mobile_responder,node_api_client,node_replay,node_producer,node_human toneIndigo
```

## Components

### Telemetry Intake

- [Connector Polling](https://github.com/beenuar/aisoc/blob/main/services/connectors/app/ingest_client.py): `services/connectors/app/ingest_client.py`
- **Ingest And Normalize**
- **Event Kafka**

### Detection And Triage

- [Detection Rules](https://github.com/beenuar/aisoc/blob/main/services/api/app/services/rule_engine.py): `services/api/app/services/rule_engine.py`
- [Alert Fusion](https://github.com/beenuar/aisoc/blob/main/services/fusion/app/services/fusion_engine.py): `services/fusion/app/services/fusion_engine.py`
- **Alert And Incident Data**

### Investigation And Response

- [AI Investigation](https://github.com/beenuar/aisoc/blob/main/plans/cyble-aisoc/platform/backend/app/agents/investigator.py): `plans/cyble-aisoc/platform/backend/app/agents/investigator.py`
- **Investigation Ledger**
- [Human Approval](https://github.com/beenuar/aisoc/blob/main/apps/web/src/app/(responder)/responder/approvals/page.tsx): `apps/web/src/app/(responder)/responder/approvals/page.tsx`
- [Playbook Execution](https://github.com/beenuar/aisoc/blob/main/services/agents/app/playbook/engine.py): `services/agents/app/playbook/engine.py`
- **Response Integrations**

### Threat Intelligence

- **Threat Feeds**
- [IOC Processing](https://github.com/beenuar/aisoc/blob/main/services/threatintel/app/feeds/pipeline.py): `services/threatintel/app/feeds/pipeline.py`
- **Intel Indexes**
- [Threat Hunting](https://github.com/beenuar/aisoc/blob/main/services/agents/app/hunt/engine.py): `services/agents/app/hunt/engine.py`

### SOC Console

- [Web SOC Console](https://github.com/beenuar/aisoc/blob/main/apps/web/src/app/(app)/dashboard/page.tsx): `apps/web/src/app/(app)/dashboard/page.tsx`
- [Mobile Responder](https://github.com/beenuar/aisoc/blob/main/apps/mobile/app/index.tsx): `apps/mobile/app/index.tsx`
- [Web API Client](https://github.com/beenuar/aisoc/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Case Replay](https://github.com/beenuar/aisoc/blob/main/apps/web/src/components/cases/replay/useReplayController.ts): `apps/web/src/components/cases/replay/useReplayController.ts`

### Other components

- **Security Tools**
- **SOC Analyst**

## Connections

- Security Tools → Ingest And Normalize: pushes events
- Security Tools → Connector Polling: provides telemetry
- Connector Polling → Ingest And Normalize: forwards normalized events
- Ingest And Normalize → Event Kafka: queues events
- Event Kafka → Detection Rules: carries events
- Detection Rules → Alert Fusion: produces matches
- Alert Fusion → Alert And Incident Data: records alerts
- Alert Fusion → AI Investigation: triggers investigation
- AI Investigation → Investigation Ledger: records reasoning
- AI Investigation → Human Approval: proposes response
- SOC Analyst → Human Approval: reviews actions
- Human Approval → Playbook Execution: authorizes execution
- Playbook Execution → Response Integrations: runs response steps
- Threat Feeds → IOC Processing: supplies indicators
- IOC Processing → Intel Indexes: indexes indicators
- Intel Indexes → Threat Hunting: provides intel
- Web SOC Console → Web API Client: uses API client
- Mobile Responder → Web API Client: uses API client
- Web API Client → Alert And Incident Data: reads SOC data
- SOC Analyst → Web SOC Console: operates console
- SOC Analyst → Mobile Responder: triages incidents
- Case Replay → Investigation Ledger: replays events