# aisecurityconsortium/aigoat architecture

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

- Interactive diagram: https://gitdiagram.com/aisecurityconsortium/aigoat
- Repository: https://github.com/aisecurityconsortium/aigoat

## Overview

AIGoat is a deliberately vulnerable AI security playground: learners exercise attacks against a local AI shopping application, observe outcomes, and compare defense levels. The main path is browser UI → FastAPI routes → a chat, RAG, agent, MCP, challenge, or kill-chain surface → LLM and application state, with defenses applied at relevant stages. The README documents the product capabilities; source evidence is sampled, so links into unsampled subsystems are limited to documented relationships or omitted.

Main entry points: [`app/main.py`](https://github.com/aisecurityconsortium/aigoat/blob/main/app/main.py) (FastAPI app), [`app/api/rag.py`](https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/rag.py) (RAG routes), [`app/api/mcp.py`](https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/mcp.py) (MCP routes), [`app/defense/pipeline.py`](https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/pipeline.py) (Defense pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learning experience"]
  node_web_ui["Learning UI<br/>[App.js]"]
  node_rag_frontend["RAG lab UI<br/>[RagDocuments.jsx]"]
  node_mcp_frontend["MCP lab UI<br/>[McpClientGuide.jsx]"]
  node_killchain_frontend["Kill Chain UI<br/>[useKillChain.js]"]
end

subgraph group_surfaces["Attack surfaces"]
  node_chat["Cracky chat<br/>[chat.py]"]
  node_rag["RAG knowledge base<br/>[service.py]"]
  node_agent["Shop agent<br/>[service.py]"]
  node_mcp["MCP surface<br/>[service.py]"]
  node_rag_api["RAG routes<br/>[rag.py]"]
  node_mcp_api["MCP routes<br/>[mcp.py]"]
end

subgraph group_protection["Defense system"]
  node_defense_pipeline["Defense pipeline<br/>[pipeline.py]"]
  node_control_chain["Control chain<br/>[chain.py]"]
  node_control_registry["Defense controls<br/>[control.py]"]
end

subgraph group_labs["Labs and evaluation"]
  node_killchain["Kill Chain<br/>[service.py]"]
  node_ingestion["Attack ingestion<br/>[ingest.py]"]
  node_challenge["CTF challenges<br/>[engine.py]"]
  node_evaluation["Challenge evaluation<br/>[evaluator.py]"]
end

subgraph group_platform["Application platform"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
  node_database[("Application database<br/>[database.py]")]
end

node_learner(("Learner"))
node_ollama["Ollama runtime"]

node_learner -->|"uses"| node_web_ui
node_web_ui -->|"calls API"| node_backend
node_backend -->|"routes requests"| node_chat
node_backend -->|"routes requests"| node_rag_api
node_backend -->|"routes requests"| node_mcp_api
node_backend -->|"offers agent"| node_agent
node_backend -->|"offers capstone"| node_killchain
node_backend -->|"offers challenges"| node_challenge
node_rag_api -->|"delegates to"| node_rag
node_mcp_api -->|"delegates to"| node_mcp
node_chat -.->|"applies defenses"| node_defense_pipeline
node_rag -->|"applies defenses"| node_defense_pipeline
node_mcp -->|"runs controls"| node_control_chain
node_defense_pipeline -->|"runs chain"| node_control_chain
node_control_chain -->|"resolves controls"| node_control_registry
node_agent -.->|"uses LLM"| node_ollama_client
node_ollama_client -->|"sends prompts"| node_ollama
node_rag_api -->|"reads and writes"| node_database
node_killchain -->|"uses ingestion"| node_ingestion
node_ingestion -->|"persists sources"| node_database
node_challenge -.->|"evaluates attempts"| node_evaluation
node_rag_frontend -.->|"manages documents"| node_rag_api
node_mcp_frontend -.->|"uses MCP labs"| node_mcp_api
node_killchain_frontend -.->|"drives capstone"| node_backend

click node_web_ui "https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/App.js"
click node_backend "https://github.com/aisecurityconsortium/aigoat/blob/main/app/main.py"
click node_chat "https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/chat.py"
click node_rag "https://github.com/aisecurityconsortium/aigoat/blob/main/app/rag/service.py"
click node_agent "https://github.com/aisecurityconsortium/aigoat/blob/main/app/agent/service.py"
click node_mcp "https://github.com/aisecurityconsortium/aigoat/blob/main/app/mcp/service.py"
click node_killchain "https://github.com/aisecurityconsortium/aigoat/blob/main/app/labs/killchain/service.py"
click node_ingestion "https://github.com/aisecurityconsortium/aigoat/blob/main/app/labs/killchain/ingest.py"
click node_challenge "https://github.com/aisecurityconsortium/aigoat/blob/main/app/challenges/engine.py"
click node_evaluation "https://github.com/aisecurityconsortium/aigoat/blob/main/app/challenges/evaluator.py"
click node_defense_pipeline "https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/pipeline.py"
click node_control_chain "https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/chain.py"
click node_control_registry "https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/control.py"
click node_ollama_client "https://github.com/aisecurityconsortium/aigoat/blob/main/app/services/ollama_client.py"
click node_database "https://github.com/aisecurityconsortium/aigoat/blob/main/app/core/database.py"
click node_rag_api "https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/rag.py"
click node_mcp_api "https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/mcp.py"
click node_rag_frontend "https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/components/rag/RagDocuments.jsx"
click node_mcp_frontend "https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/components/mcp/McpClientGuide.jsx"
click node_killchain_frontend "https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/components/killchain/useKillChain.js"

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_ui,node_rag_frontend,node_mcp_frontend,node_killchain_frontend toneBlue
class node_chat,node_rag,node_agent,node_mcp,node_rag_api,node_mcp_api toneAmber
class node_defense_pipeline,node_control_chain,node_control_registry toneMint
class node_killchain,node_ingestion,node_challenge,node_evaluation toneRose
class node_backend,node_ollama_client,node_database,node_learner,node_ollama toneIndigo
```

## Components

### Learning experience

- [Learning UI](https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [RAG lab UI](https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/components/rag/RagDocuments.jsx): `frontend/src/components/rag/RagDocuments.jsx`
- [MCP lab UI](https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/components/mcp/McpClientGuide.jsx): `frontend/src/components/mcp/McpClientGuide.jsx`
- [Kill Chain UI](https://github.com/aisecurityconsortium/aigoat/blob/main/frontend/src/components/killchain/useKillChain.js): `frontend/src/components/killchain/useKillChain.js`

### Attack surfaces

- [Cracky chat](https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/chat.py): `app/api/chat.py`
- [RAG knowledge base](https://github.com/aisecurityconsortium/aigoat/blob/main/app/rag/service.py): `app/rag/service.py`
- [Shop agent](https://github.com/aisecurityconsortium/aigoat/blob/main/app/agent/service.py): `app/agent/service.py`
- [MCP surface](https://github.com/aisecurityconsortium/aigoat/blob/main/app/mcp/service.py): `app/mcp/service.py`
- [RAG routes](https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/rag.py): `app/api/rag.py`
- [MCP routes](https://github.com/aisecurityconsortium/aigoat/blob/main/app/api/mcp.py): `app/api/mcp.py`

### Defense system

- [Defense pipeline](https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/pipeline.py): `app/defense/pipeline.py`
- [Control chain](https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/chain.py): `app/defense/chain.py`
- [Defense controls](https://github.com/aisecurityconsortium/aigoat/blob/main/app/defense/control.py): `app/defense/control.py`

### Labs and evaluation

- [Kill Chain](https://github.com/aisecurityconsortium/aigoat/blob/main/app/labs/killchain/service.py): `app/labs/killchain/service.py`
- [Attack ingestion](https://github.com/aisecurityconsortium/aigoat/blob/main/app/labs/killchain/ingest.py): `app/labs/killchain/ingest.py`
- [CTF challenges](https://github.com/aisecurityconsortium/aigoat/blob/main/app/challenges/engine.py): `app/challenges/engine.py`
- [Challenge evaluation](https://github.com/aisecurityconsortium/aigoat/blob/main/app/challenges/evaluator.py): `app/challenges/evaluator.py`

### Application platform

- [FastAPI app](https://github.com/aisecurityconsortium/aigoat/blob/main/app/main.py): `app/main.py`
- [Ollama client](https://github.com/aisecurityconsortium/aigoat/blob/main/app/services/ollama_client.py): `app/services/ollama_client.py`
- [Application database](https://github.com/aisecurityconsortium/aigoat/blob/main/app/core/database.py): `app/core/database.py`

### Other components

- **Learner**
- **Ollama runtime**

## Connections

- Learner → Learning UI: uses (evidence: `README.md`)
- Learning UI → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Cracky chat: routes requests (evidence: `app/main.py`)
- FastAPI app → RAG routes: routes requests (evidence: `app/main.py`)
- FastAPI app → MCP routes: routes requests (evidence: `app/main.py`)
- FastAPI app → Shop agent: offers agent (evidence: `README.md`)
- FastAPI app → Kill Chain: offers capstone (evidence: `README.md`)
- FastAPI app → CTF challenges: offers challenges (evidence: `README.md`)
- RAG routes → RAG knowledge base: delegates to (evidence: `app/api/rag.py`)
- MCP routes → MCP surface: delegates to (evidence: `app/api/mcp.py`)
- Cracky chat → Defense pipeline: applies defenses
- RAG knowledge base → Defense pipeline: applies defenses (evidence: `app/rag/service.py`)
- MCP surface → Control chain: runs controls (evidence: `app/mcp/service.py`)
- Defense pipeline → Control chain: runs chain (evidence: `app/defense/pipeline.py`)
- Control chain → Defense controls: resolves controls (evidence: `app/defense/chain.py`)
- Shop agent → Ollama client: uses LLM (evidence: `app/agent/service.py`)
- Ollama client → Ollama runtime: sends prompts (evidence: `app/services/ollama_client.py`)
- RAG routes → Application database: reads and writes (evidence: `app/api/rag.py`)
- Kill Chain → Attack ingestion: uses ingestion (evidence: `app/labs/killchain/service.py`)
- Attack ingestion → Application database: persists sources (evidence: `app/labs/killchain/ingest.py`)
- CTF challenges → Challenge evaluation: evaluates attempts
- RAG lab UI → RAG routes: manages documents
- MCP lab UI → MCP routes: uses MCP labs
- Kill Chain UI → FastAPI app: drives capstone