# cmu-sei/ghosts architecture

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

- Interactive diagram: https://gitdiagram.com/cmu-sei/ghosts
- Repository: https://github.com/cmu-sei/ghosts

## Overview

GHOSTS is an NPC orchestration framework for cyber training and simulation. Its main workflow is to configure scenarios and timelines, manage machines and NPCs, deliver activity to installed clients, and monitor execution through the management UI and supporting services. The graph also preserves persona generation, scenario authoring, content generation, and workflow automation. Relationships are limited to those stated in the README or visible in excerpts; unsampled subsystem connections are omitted where their caller is not established.

Main entry points: [`src/Ghosts.Api/Program.cs`](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Program.cs) (GHOSTS API), [`src/Ghosts.Api/Infrastructure/Services`](https://github.com/cmu-sei/ghosts/tree/master/src/Ghosts.Api/Infrastructure/Services) (Execution orchestration), [`src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs`](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs) (Scenario authoring), [`src/Ghosts.Frontend/src/app/app.routes.ts`](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Frontend/src/app/app.routes.ts) (Management UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Management"]
  node_frontend["Management UI<br/>[app.routes.ts]"]
  node_api["GHOSTS API<br/>[Program.cs]"]
  node_database[("PostgreSQL store")]
end

subgraph group_scenario["Scenario lifecycle"]
  node_authoring["Scenario authoring"]
  node_scenario_models["Scenario model<br/>[Scenarios.cs]"]
  node_scenario_validation["Document validation"]
  node_scenario_findings["Validation findings<br/>[ScenarioFinding.cs]"]
end

subgraph group_orchestration["Orchestration"]
  node_timeline["Timeline definitions<br/>[Timeline.cs]"]
  node_execution["Execution orchestration<br/>[Services]"]
end

subgraph group_agents["Client agents"]
  node_windows_client["Windows client<br/>[Program.cs]"]
  node_universal_client["Universal client<br/>[Program.cs]"]
  node_lite_client["Lite client<br/>[Program.cs]"]
end

subgraph group_support["Supporting services"]
  node_animator["NPC persona engine<br/>[NpcProfile.cs]"]
  node_pandora["Content generation"]
  node_n8n["Workflow automation"]
  node_grafana["Activity dashboards"]
end

node_operator(("Exercise operator"))
node_client_operator(("Simulated machine"))

node_operator -->|"manages exercises"| node_frontend
node_frontend -->|"uses management API"| node_api
node_api -->|"persists state"| node_database
node_api -.->|"supports authoring"| node_authoring
node_authoring -->|"creates scenarios"| node_scenario_models
node_authoring -->|"validates documents"| node_scenario_validation
node_scenario_validation -->|"produces findings"| node_scenario_findings
node_api -.->|"orchestrates activity"| node_execution
node_execution -.->|"dispatches timelines"| node_timeline
node_execution -.->|"deploys activity"| node_windows_client
node_execution -.->|"deploys activity"| node_universal_client
node_execution -.->|"deploys activity"| node_lite_client
node_client_operator -->|"runs agent"| node_windows_client
node_client_operator -->|"runs agent"| node_universal_client
node_client_operator -->|"runs agent"| node_lite_client
node_api -->|"schedules workflows"| node_n8n
node_api -.->|"provides activity data"| node_grafana

click node_frontend "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Frontend/src/app/app.routes.ts"
click node_api "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Program.cs"
click node_database "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Data/ApplicationDbContext.cs"
click node_authoring "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs"
click node_scenario_models "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Models/Scenarios.cs"
click node_scenario_validation "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioDocumentValidator.cs"
click node_scenario_findings "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioFinding.cs"
click node_timeline "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Domain/Messages/Timeline.cs"
click node_execution "https://github.com/cmu-sei/ghosts/tree/master/src/Ghosts.Api/Infrastructure/Services"
click node_windows_client "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Client.Windows/Program.cs"
click node_universal_client "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Client.Universal/Program.cs"
click node_lite_client "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Client.Lite/src/Program.cs"
click node_animator "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Animator/Models/NpcProfile.cs"
click node_pandora "https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Pandora/src/Controllers/PandoraController.cs"

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_frontend,node_api,node_database toneBlue
class node_authoring,node_scenario_models,node_scenario_validation,node_scenario_findings toneAmber
class node_timeline,node_execution toneMint
class node_windows_client,node_universal_client,node_lite_client toneRose
class node_animator,node_pandora,node_n8n,node_grafana,node_operator,node_client_operator toneIndigo
```

## Components

### Management

- [Management UI](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Frontend/src/app/app.routes.ts): `src/Ghosts.Frontend/src/app/app.routes.ts`
- [GHOSTS API](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Program.cs): `src/Ghosts.Api/Program.cs`
- [PostgreSQL store](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Data/ApplicationDbContext.cs): `src/Ghosts.Api/Infrastructure/Data/ApplicationDbContext.cs`

### Scenario lifecycle

- [Scenario authoring](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs): `src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs`
- [Scenario model](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/Models/Scenarios.cs): `src/Ghosts.Api/Infrastructure/Models/Scenarios.cs`
- [Document validation](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioDocumentValidator.cs): `src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioDocumentValidator.cs`
- [Validation findings](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioFinding.cs): `src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioFinding.cs`

### Orchestration

- [Timeline definitions](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Domain/Messages/Timeline.cs): `src/Ghosts.Domain/Messages/Timeline.cs`
- [Execution orchestration](https://github.com/cmu-sei/ghosts/tree/master/src/Ghosts.Api/Infrastructure/Services): `src/Ghosts.Api/Infrastructure/Services`

### Client agents

- [Windows client](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Client.Windows/Program.cs): `src/Ghosts.Client.Windows/Program.cs`
- [Universal client](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Client.Universal/Program.cs): `src/Ghosts.Client.Universal/Program.cs`
- [Lite client](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Client.Lite/src/Program.cs): `src/Ghosts.Client.Lite/src/Program.cs`

### Supporting services

- [NPC persona engine](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Animator/Models/NpcProfile.cs): `src/Ghosts.Animator/Models/NpcProfile.cs`
- [Content generation](https://github.com/cmu-sei/ghosts/blob/master/src/Ghosts.Pandora/src/Controllers/PandoraController.cs): `src/Ghosts.Pandora/src/Controllers/PandoraController.cs`
- **Workflow automation**
- **Activity dashboards**

### Other components

- **Exercise operator**
- **Simulated machine**

## Connections

- Exercise operator → Management UI: manages exercises (evidence: `README.md`)
- Management UI → GHOSTS API: uses management API (evidence: `README.md`)
- GHOSTS API → PostgreSQL store: persists state (evidence: `README.md`)
- GHOSTS API → Scenario authoring: supports authoring
- Scenario authoring → Scenario model: creates scenarios (evidence: `src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs`)
- Scenario authoring → Document validation: validates documents (evidence: `src/Ghosts.Api/Infrastructure/Services/ScenarioAuthoringService.cs`)
- Document validation → Validation findings: produces findings (evidence: `src/Ghosts.Api/Infrastructure/ScenarioDocuments/ScenarioFinding.cs`)
- GHOSTS API → Execution orchestration: orchestrates activity
- Execution orchestration → Timeline definitions: dispatches timelines (evidence: `src/Ghosts.Api/Infrastructure/Services/ScenarioService.cs`)
- Execution orchestration → Windows client: deploys activity
- Execution orchestration → Universal client: deploys activity
- Execution orchestration → Lite client: deploys activity
- Simulated machine → Windows client: runs agent (evidence: `README.md`)
- Simulated machine → Universal client: runs agent (evidence: `README.md`)
- Simulated machine → Lite client: runs agent (evidence: `README.md`)
- GHOSTS API → Workflow automation: schedules workflows (evidence: `README.md`)
- GHOSTS API → Activity dashboards: provides activity data
