# kh4nh709/ai_support_soc_1_2 architecture

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

- Interactive diagram: https://gitdiagram.com/kh4nh709/ai_support_soc_1_2
- Repository: https://github.com/kh4nh709/ai_support_soc_1_2

## Overview

AI Support SOC là ứng dụng hỗ trợ analyst xử lý alert Wazuh qua Tier 1 và Tier 2; LLM đề xuất, con người quyết định. Luồng chính đi từ tiếp nhận, chuẩn hóa, loại trùng, enrichment và chấm rủi ro tới hàng đợi, triage, bàn giao case, điều tra và kết luận. Sơ đồ cũng thể hiện các nhánh xác thực, bảo vệ prompt và audit. README mô tả một số năng lực chưa có excerpt nguồn tương ứng; các liên kết của chúng chỉ phản ánh luồng được tài liệu nêu, không suy diễn chi tiết triển khai.

Main entry points: [`backend/app/soar/pipeline.py`](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/soar/pipeline.py) (Alert pipeline), [`backend/app/infra/db.py`](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/db.py) (Application database), [`backend/app/tier1/triage.py`](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/triage.py) (LLM triage), [`backend/app/tier2/investigate.py`](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier2/investigate.py) (Tier 2 investigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Tiếp nhận alert"]
  node_webhook["Webhook intake<br/>[webhook.py]"]
  node_intake_service["Intake service<br/>[intake.py]"]
  node_parser["Wazuh parser<br/>[wazuh_parser.py]"]
end

subgraph group_processing["Xử lý tự động"]
  node_pipeline["Alert pipeline<br/>[pipeline.py]"]
  node_dedup["Deduplication<br/>[dedup.py]"]
  node_enrichment["Context enrichment<br/>[lookups.py]"]
  node_risk["Risk scoring<br/>[risk.py]"]
  node_transitions["Alert transitions<br/>[transitions.py]"]
end

subgraph group_analyst["Workflow analyst"]
  node_tier1_queue["Tier 1 queue<br/>[queue.py]"]
  node_tier1_triage["LLM triage<br/>[triage.py]"]
  node_tier1_decision["Tier 1 decision<br/>[decide.py]"]
  node_tier2_investigate["Tier 2 investigation<br/>[investigate.py]"]
  node_tier2_conclude["Tier 2 conclusion<br/>[conclude.py]"]
end

subgraph group_llm_safety["LLM và an toàn"]
  node_llm["LLM adapter<br/>[adapter.py]"]
  node_prompt_builder["Prompt builder<br/>[prompt_builder.py]"]
  node_security["Prompt safeguards<br/>[wrap.py]"]
  node_audit_runs["LLM run audit<br/>[llm_runs.py]"]
end

subgraph group_platform["Web và nền tảng"]
  node_worker_root["Worker composition<br/>[worker.py]"]
  node_worker_loop["Job worker<br/>[worker.py]"]
  node_web_app["Web application<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database[("Application database<br/>[db.py]")]
end

node_wazuh(("Wazuh"))
node_analyst_user(("SOC analyst"))

node_wazuh -->|"sends alerts"| node_webhook
node_webhook -->|"passes payload"| node_intake_service
node_intake_service -->|"records intake"| node_database
node_worker_root -->|"runs handlers"| node_worker_loop
node_worker_root -->|"registers handler"| node_pipeline
node_worker_loop -->|"dispatches job"| node_pipeline
node_pipeline -->|"reads intake"| node_database
node_pipeline -->|"parses alert"| node_parser
node_pipeline -->|"checks cluster"| node_dedup
node_pipeline -->|"builds context"| node_enrichment
node_pipeline -->|"scores alert"| node_risk
node_pipeline -->|"writes transitions"| node_transitions
node_pipeline -->|"writes outcomes"| node_database
node_transitions -->|"persists state"| node_database
node_pipeline -->|"queues triage"| node_tier1_queue
node_tier1_queue -->|"provides queued alert"| node_tier1_triage
node_tier1_triage -->|"builds prompt"| node_prompt_builder
node_prompt_builder -->|"wraps untrusted data"| node_security
node_tier1_triage -->|"requests proposal"| node_llm
node_tier1_triage -->|"records model run"| node_audit_runs
node_tier1_decision -.->|"escalates case"| node_tier2_investigate
node_tier2_investigate -.->|"builds prompt"| node_prompt_builder
node_tier2_investigate -.->|"requests assistance"| node_llm
node_tier2_investigate -.->|"submits findings"| node_tier2_conclude
node_analyst_user -->|"decides triage"| node_tier1_decision
node_analyst_user -->|"reviews conclusion"| node_tier2_conclude
node_web_app -->|"mounts routes"| node_auth_routes
node_auth_routes -->|"authenticates"| node_auth
node_auth_routes -->|"uses connection"| node_database
node_auth -->|"checks user state"| node_database

click node_webhook "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/routers/webhook.py"
click node_intake_service "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/intake.py"
click node_parser "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/ingest/wazuh_parser.py"
click node_worker_root "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/worker.py"
click node_worker_loop "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/worker.py"
click node_pipeline "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/soar/pipeline.py"
click node_dedup "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/ingest/dedup.py"
click node_enrichment "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/enrichment/lookups.py"
click node_risk "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/soar/risk.py"
click node_transitions "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/domain/transitions.py"
click node_tier1_queue "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/queue.py"
click node_tier1_triage "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/triage.py"
click node_tier1_decision "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/decide.py"
click node_tier2_investigate "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier2/investigate.py"
click node_tier2_conclude "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier2/conclude.py"
click node_llm "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/llm/adapter.py"
click node_prompt_builder "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/llm/prompt_builder.py"
click node_security "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/security/wrap.py"
click node_audit_runs "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/audit/llm_runs.py"
click node_web_app "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/main.py"
click node_auth_routes "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/routers/auth.py"
click node_auth "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/auth.py"
click node_database "https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/db.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_webhook,node_intake_service,node_parser toneBlue
class node_pipeline,node_dedup,node_enrichment,node_risk,node_transitions toneAmber
class node_tier1_queue,node_tier1_triage,node_tier1_decision,node_tier2_investigate,node_tier2_conclude toneMint
class node_llm,node_prompt_builder,node_security,node_audit_runs toneRose
class node_worker_root,node_worker_loop,node_web_app,node_auth_routes,node_auth,node_database,node_wazuh,node_analyst_user toneIndigo
```

## Components

### Tiếp nhận alert

- [Webhook intake](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/routers/webhook.py): `backend/app/web/routers/webhook.py`
- [Intake service](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/intake.py): `backend/app/infra/intake.py`
- [Wazuh parser](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/ingest/wazuh_parser.py): `backend/app/ingest/wazuh_parser.py`

### Xử lý tự động

- [Alert pipeline](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/soar/pipeline.py): `backend/app/soar/pipeline.py`
- [Deduplication](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/ingest/dedup.py): `backend/app/ingest/dedup.py`
- [Context enrichment](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/enrichment/lookups.py): `backend/app/enrichment/lookups.py`
- [Risk scoring](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/soar/risk.py): `backend/app/soar/risk.py`
- [Alert transitions](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/domain/transitions.py): `backend/app/domain/transitions.py`

### Workflow analyst

- [Tier 1 queue](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/queue.py): `backend/app/tier1/queue.py`
- [LLM triage](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/triage.py): `backend/app/tier1/triage.py`
- [Tier 1 decision](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier1/decide.py): `backend/app/tier1/decide.py`
- [Tier 2 investigation](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier2/investigate.py): `backend/app/tier2/investigate.py`
- [Tier 2 conclusion](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/tier2/conclude.py): `backend/app/tier2/conclude.py`

### LLM và an toàn

- [LLM adapter](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/llm/adapter.py): `backend/app/llm/adapter.py`
- [Prompt builder](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/llm/prompt_builder.py): `llm/prompt_builder.py`
- [Prompt safeguards](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/security/wrap.py): `backend/app/security/wrap.py`
- [LLM run audit](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/audit/llm_runs.py): `backend/app/audit/llm_runs.py`

### Web và nền tảng

- [Worker composition](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/worker.py): `backend/app/web/worker.py`
- [Job worker](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/worker.py): `backend/app/infra/worker.py`
- [Web application](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/main.py): `backend/app/web/main.py`
- [Auth routes](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/web/routers/auth.py): `backend/app/web/routers/auth.py`
- [Authentication](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/auth.py): `backend/app/infra/auth.py`
- [Application database](https://github.com/kh4nh709/ai_support_soc_1_2/blob/main/backend/app/infra/db.py): `backend/app/infra/db.py`

### Other components

- **Wazuh**
- **SOC analyst**

## Connections

- Wazuh → Webhook intake: sends alerts
- Webhook intake → Intake service: passes payload
- Intake service → Application database: records intake
- Worker composition → Job worker: runs handlers
- Worker composition → Alert pipeline: registers handler
- Job worker → Alert pipeline: dispatches job
- Alert pipeline → Application database: reads intake
- Alert pipeline → Wazuh parser: parses alert
- Alert pipeline → Deduplication: checks cluster
- Alert pipeline → Context enrichment: builds context
- Alert pipeline → Risk scoring: scores alert
- Alert pipeline → Alert transitions: writes transitions
- Alert pipeline → Application database: writes outcomes
- Alert transitions → Application database: persists state
- Alert pipeline → Tier 1 queue: queues triage
- Tier 1 queue → LLM triage: provides queued alert
- LLM triage → Prompt builder: builds prompt
- Prompt builder → Prompt safeguards: wraps untrusted data
- LLM triage → LLM adapter: requests proposal
- LLM triage → LLM run audit: records model run
- Tier 1 decision → Tier 2 investigation: escalates case
- Tier 2 investigation → Prompt builder: builds prompt
- Tier 2 investigation → LLM adapter: requests assistance
- Tier 2 investigation → Tier 2 conclusion: submits findings
- SOC analyst → Tier 1 decision: decides triage
- SOC analyst → Tier 2 conclusion: reviews conclusion
- Web application → Auth routes: mounts routes
- Auth routes → Authentication: authenticates
- Auth routes → Application database: uses connection
- Authentication → Application database: checks user state