# mints-ai/shield-desk architecture

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

- Interactive diagram: https://gitdiagram.com/mints-ai/shield-desk
- Repository: https://github.com/mints-ai/shield-desk

## Overview

ShieldDesk is a multi-tenant security operations platform: analysts ingest alerts, investigate incidents and vulnerability exposure, plan mitigations, obtain tiered human approval, and coordinate endpoint response. Its Next.js gateway connects dashboards and APIs to persistence, local AI, and dedicated ingest, scan, threat, advisor, identity, webhook, and agent services. The README documents major capabilities not fully represented in sampled source; those branches are shown at supported directory paths, while uncertain internal wiring is omitted.

Main entry points: [`src/lib/db/index.ts`](https://github.com/mints-ai/shield-desk/blob/main/src/lib/db/index.ts) (Tenant data store), [`src/app/api`](https://github.com/mints-ai/shield-desk/tree/main/src/app/api) (Next.js APIs), [`src/app/dashboard`](https://github.com/mints-ai/shield-desk/tree/main/src/app/dashboard) (SOC dashboards), [`src/app/api/chat/route.ts`](https://github.com/mints-ai/shield-desk/blob/main/src/app/api/chat/route.ts) (AI chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["SOC Operations"]
  node_dashboard["SOC dashboards"]
  node_chat_ui["AI chat drawer<br/>[ChatWidget.tsx]"]
  node_incident_data[("Incident records<br/>[route.ts]")]
  node_compliance["Compliance evidence<br/>[iso27001.ts]"]
  node_scorecard["Executive scorecard<br/>[scorecard.ts]"]
end

subgraph group_gateway["API Gateway"]
  node_api["Next.js APIs"]
  node_auth["Identity and sessions"]
  node_ingest_api["Webhook ingestion<br/>[route.ts]"]
  node_advisor_api["AI advisor API<br/>[route.ts]"]
  node_chat_api["AI chat API<br/>[route.ts]"]
  node_tools["SOC chat tools<br/>[index.ts]"]
end

subgraph group_intelligence["Security Intelligence"]
  node_ingest_service["Telemetry ingestion"]
  node_threat["Threat detection"]
  node_scanner["Vulnerability scanner"]
  node_ml_engine["CVE ML engine<br/>[cve_ai_engine.py]"]
  node_ml_api["ML service<br/>[server.py]"]
  node_advisor["Advisor RAG"]
end

subgraph group_response["Governance Response"]
  node_agent["Endpoint agents<br/>[actions.go]"]
  node_rust_daemon["Tier 3 daemon<br/>[main.rs]"]
  node_governance["Approval governance<br/>[approvalTokens.ts]"]
  node_fleet["Fleet commands<br/>[fleet.ts]"]
  node_notifications["Alert dispatcher<br/>[dispatcher.ts]"]
  node_webhooks["Webhook dispatcher"]
end

subgraph group_runtime["Platform Services"]
  node_db[("Tenant data store<br/>[index.ts]")]
  node_ollama["Local Ollama<br/>[ollama.ts]"]
end

node_analyst(("Analyst"))
node_external_siem(("SIEM / EDR"))
node_external_hooks(("Slack / Teams"))

node_analyst -->|"uses"| node_dashboard
node_analyst -->|"asks"| node_chat_ui
node_dashboard -->|"requests"| node_api
node_chat_ui -->|"streams chat"| node_chat_api
node_api -->|"authenticates"| node_auth
node_api -->|"reads and writes"| node_db
node_ingest_api -->|"receives alerts"| node_external_siem
node_ingest_api -->|"writes incidents"| node_db
node_ingest_api -->|"dispatches alert"| node_notifications
node_ingest_service -.->|"persists telemetry"| node_db
node_agent -.->|"sends telemetry"| node_db
node_rust_daemon -.->|"sends telemetry"| node_db
node_threat -.->|"uses threat data"| node_db
node_scanner -.->|"requests analysis"| node_ml_api
node_ml_api -->|"predicts CVE risk"| node_ml_engine
node_api -.->|"requests scans"| node_scanner
node_advisor_api -->|"requests runbook"| node_advisor
node_chat_api -->|"routes and streams"| node_ollama
node_chat_api -->|"dispatches tools"| node_tools
node_chat_api -->|"checks permissions"| node_governance
node_tools -->|"queries SOC data"| node_db
node_governance -.->|"stores approvals"| node_db
node_api -.->|"dispatches commands"| node_fleet
node_fleet -.->|"commands fleet"| node_agent
node_fleet -.->|"high-risk actions"| node_rust_daemon
node_notifications -.->|"dispatches events"| node_webhooks
node_webhooks -.->|"delivers alerts"| node_external_hooks
node_compliance -.->|"assembles evidence"| node_db
node_scorecard -.->|"reads posture data"| node_db
node_dashboard -.->|"views evidence"| node_compliance
node_dashboard -.->|"views posture"| node_scorecard

click node_dashboard "https://github.com/mints-ai/shield-desk/tree/main/src/app/dashboard"
click node_chat_ui "https://github.com/mints-ai/shield-desk/blob/main/src/components/ai-chat/ChatWidget.tsx"
click node_api "https://github.com/mints-ai/shield-desk/tree/main/src/app/api"
click node_auth "https://github.com/mints-ai/shield-desk/tree/main/services/iam/src"
click node_ingest_api "https://github.com/mints-ai/shield-desk/blob/main/src/app/api/ingest/webhooks/route.ts"
click node_db "https://github.com/mints-ai/shield-desk/blob/main/src/lib/db/index.ts"
click node_incident_data "https://github.com/mints-ai/shield-desk/blob/main/src/app/api/ingest/webhooks/route.ts"
click node_ingest_service "https://github.com/mints-ai/shield-desk/tree/main/services/ingest"
click node_agent "https://github.com/mints-ai/shield-desk/blob/main/agent/pkg/handlers/actions.go"
click node_rust_daemon "https://github.com/mints-ai/shield-desk/blob/main/agent/rust_daemon/src/main.rs"
click node_threat "https://github.com/mints-ai/shield-desk/tree/main/services/threat"
click node_scanner "https://github.com/mints-ai/shield-desk/tree/main/services/scan"
click node_ml_engine "https://github.com/mints-ai/shield-desk/blob/main/ai-chat-desk/cve_ai_engine.py"
click node_ml_api "https://github.com/mints-ai/shield-desk/blob/main/ai-chat-desk/server.py"
click node_advisor_api "https://github.com/mints-ai/shield-desk/blob/main/src/app/api/ai/advisor/route.ts"
click node_advisor "https://github.com/mints-ai/shield-desk/tree/main/services/ai-advisor"
click node_chat_api "https://github.com/mints-ai/shield-desk/blob/main/src/app/api/chat/route.ts"
click node_tools "https://github.com/mints-ai/shield-desk/blob/main/src/lib/tools/index.ts"
click node_ollama "https://github.com/mints-ai/shield-desk/blob/main/src/lib/ai/ollama.ts"
click node_governance "https://github.com/mints-ai/shield-desk/blob/main/src/lib/governance/approvalTokens.ts"
click node_fleet "https://github.com/mints-ai/shield-desk/blob/main/src/lib/fleet/fleet.ts"
click node_notifications "https://github.com/mints-ai/shield-desk/blob/main/src/lib/notifications/dispatcher.ts"
click node_webhooks "https://github.com/mints-ai/shield-desk/tree/main/services/webhooks"
click node_compliance "https://github.com/mints-ai/shield-desk/blob/main/src/lib/compliance/iso27001.ts"
click node_scorecard "https://github.com/mints-ai/shield-desk/blob/main/src/lib/reporting/scorecard.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_dashboard,node_chat_ui,node_incident_data,node_compliance,node_scorecard toneBlue
class node_api,node_auth,node_ingest_api,node_advisor_api,node_chat_api,node_tools toneAmber
class node_ingest_service,node_threat,node_scanner,node_ml_engine,node_ml_api,node_advisor toneMint
class node_agent,node_rust_daemon,node_governance,node_fleet,node_notifications,node_webhooks toneRose
class node_db,node_ollama,node_analyst,node_external_siem,node_external_hooks toneIndigo
```

## Components

### SOC Operations

- [SOC dashboards](https://github.com/mints-ai/shield-desk/tree/main/src/app/dashboard): `src/app/dashboard`
- [AI chat drawer](https://github.com/mints-ai/shield-desk/blob/main/src/components/ai-chat/ChatWidget.tsx): `src/components/ai-chat/ChatWidget.tsx`
- [Incident records](https://github.com/mints-ai/shield-desk/blob/main/src/app/api/ingest/webhooks/route.ts): `src/app/api/ingest/webhooks/route.ts`
- [Compliance evidence](https://github.com/mints-ai/shield-desk/blob/main/src/lib/compliance/iso27001.ts): `src/lib/compliance/iso27001.ts`
- [Executive scorecard](https://github.com/mints-ai/shield-desk/blob/main/src/lib/reporting/scorecard.ts): `src/lib/reporting/scorecard.ts`

### API Gateway

- [Next.js APIs](https://github.com/mints-ai/shield-desk/tree/main/src/app/api): `src/app/api`
- [Identity and sessions](https://github.com/mints-ai/shield-desk/tree/main/services/iam/src): `services/iam/src`
- [Webhook ingestion](https://github.com/mints-ai/shield-desk/blob/main/src/app/api/ingest/webhooks/route.ts): `src/app/api/ingest/webhooks/route.ts`
- [AI advisor API](https://github.com/mints-ai/shield-desk/blob/main/src/app/api/ai/advisor/route.ts): `src/app/api/ai/advisor/route.ts`
- [AI chat API](https://github.com/mints-ai/shield-desk/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [SOC chat tools](https://github.com/mints-ai/shield-desk/blob/main/src/lib/tools/index.ts): `src/lib/tools/index.ts`

### Security Intelligence

- [Telemetry ingestion](https://github.com/mints-ai/shield-desk/tree/main/services/ingest): `services/ingest`
- [Threat detection](https://github.com/mints-ai/shield-desk/tree/main/services/threat): `services/threat`
- [Vulnerability scanner](https://github.com/mints-ai/shield-desk/tree/main/services/scan): `services/scan`
- [CVE ML engine](https://github.com/mints-ai/shield-desk/blob/main/ai-chat-desk/cve_ai_engine.py): `ai-chat-desk/cve_ai_engine.py`
- [ML service](https://github.com/mints-ai/shield-desk/blob/main/ai-chat-desk/server.py): `ai-chat-desk/server.py`
- [Advisor RAG](https://github.com/mints-ai/shield-desk/tree/main/services/ai-advisor): `services/ai-advisor`

### Governance Response

- [Endpoint agents](https://github.com/mints-ai/shield-desk/blob/main/agent/pkg/handlers/actions.go): `agent/pkg/handlers/actions.go`
- [Tier 3 daemon](https://github.com/mints-ai/shield-desk/blob/main/agent/rust_daemon/src/main.rs): `agent/rust_daemon/src/main.rs`
- [Approval governance](https://github.com/mints-ai/shield-desk/blob/main/src/lib/governance/approvalTokens.ts): `src/lib/governance/approvalTokens.ts`
- [Fleet commands](https://github.com/mints-ai/shield-desk/blob/main/src/lib/fleet/fleet.ts): `src/lib/fleet/fleet.ts`
- [Alert dispatcher](https://github.com/mints-ai/shield-desk/blob/main/src/lib/notifications/dispatcher.ts): `src/lib/notifications/dispatcher.ts`
- [Webhook dispatcher](https://github.com/mints-ai/shield-desk/tree/main/services/webhooks): `services/webhooks`

### Platform Services

- [Tenant data store](https://github.com/mints-ai/shield-desk/blob/main/src/lib/db/index.ts): `src/lib/db/index.ts`
- [Local Ollama](https://github.com/mints-ai/shield-desk/blob/main/src/lib/ai/ollama.ts): `src/lib/ai/ollama.ts`

### Other components

- **Analyst**
- **SIEM / EDR**
- **Slack / Teams**

## Connections

- Analyst → SOC dashboards: uses
- Analyst → AI chat drawer: asks
- SOC dashboards → Next.js APIs: requests
- AI chat drawer → AI chat API: streams chat
- Next.js APIs → Identity and sessions: authenticates
- Next.js APIs → Tenant data store: reads and writes
- Webhook ingestion → SIEM / EDR: receives alerts
- Webhook ingestion → Tenant data store: writes incidents
- Webhook ingestion → Alert dispatcher: dispatches alert
- Telemetry ingestion → Tenant data store: persists telemetry
- Endpoint agents → Tenant data store: sends telemetry
- Tier 3 daemon → Tenant data store: sends telemetry
- Threat detection → Tenant data store: uses threat data
- Vulnerability scanner → ML service: requests analysis
- ML service → CVE ML engine: predicts CVE risk
- Next.js APIs → Vulnerability scanner: requests scans
- AI advisor API → Advisor RAG: requests runbook
- AI chat API → Local Ollama: routes and streams
- AI chat API → SOC chat tools: dispatches tools
- AI chat API → Approval governance: checks permissions
- SOC chat tools → Tenant data store: queries SOC data
- Approval governance → Tenant data store: stores approvals
- Next.js APIs → Fleet commands: dispatches commands
- Fleet commands → Endpoint agents: commands fleet
- Fleet commands → Tier 3 daemon: high-risk actions
- Alert dispatcher → Webhook dispatcher: dispatches events
- Webhook dispatcher → Slack / Teams: delivers alerts
- Compliance evidence → Tenant data store: assembles evidence
- Executive scorecard → Tenant data store: reads posture data
- SOC dashboards → Compliance evidence: views evidence
- SOC dashboards → Executive scorecard: views posture