# mitre/heimdall2 architecture

> Architecture diagram of the GitHub repository mitre/heimdall2, 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/mitre/heimdall2
- Repository: https://github.com/mitre/heimdall2

## Overview

Heimdall is a security-assessment results viewer and reporting system, offered as a standalone Lite frontend or as a server-backed application. The principal workflow is to load assessment data, convert supported formats to Heimdall’s representation, review and compare results, and produce reports; the server adds persistent evaluations, users, groups, and an authenticated REST API. The map includes documented capabilities and sampled backend relationships. Several frontend-to-backend and converter-to-frontend links are documented at product level but their runtime wiring was not sampled.

Main entry points: [`apps/backend/src/evaluations/evaluations.controller.ts`](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluations.controller.ts) (Evaluation API), [`apps/backend/src/groups/groups.service.ts`](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/groups/groups.service.ts) (Groups and sharing), [`apps/frontend/src/App.vue`](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/App.vue) (Heimdall UI), [`apps/frontend/src/views/Results.vue`](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/views/Results.vue) (Review views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Review and reporting"]
  node_frontend["Heimdall UI<br/>[App.vue]"]
  node_views["Review views<br/>[Results.vue]"]
  node_compare["Comparison view<br/>[Compare.vue]"]
  node_exports["Report exports"]
  node_frontend_state["Frontend state and API<br/>[server.ts]"]
end

subgraph group_ingest["Ingestion and formats"]
  node_upload["Upload interfaces<br/>[FileReader.vue]"]
  node_converters["OHDF converters<br/>[base-converter.ts]"]
  node_inspec["InSpec parsing<br/>[context.ts]"]
end

subgraph group_api["Backend API"]
  node_evaluation_api["Evaluation API"]
  node_evaluation_service["Evaluation service"]
  node_tags_stats["Tags and statistics"]
end

subgraph group_identity["Identity and access"]
  node_authn["Authentication<br/>[authn.service.ts]"]
  node_authz["Authorization"]
  node_user_mgmt["User management<br/>[users.service.ts]"]
  node_group_mgmt["Groups and sharing<br/>[groups.service.ts]"]
end

subgraph group_persistence["Persistent data"]
  node_eval_store[("Evaluation records")]
  node_user_store[("User records<br/>[user.model.ts]")]
  node_group_store[("Group records<br/>[group.model.ts]")]
end

node_user(("Assessor"))
node_postgres[("PostgreSQL")]
node_external_sources(("External data sources"))

node_user -->|"reviews"| node_frontend
node_frontend -->|"loads reports"| node_upload
node_upload -.->|"converts formats"| node_converters
node_inspec -.->|"parses InSpec"| node_converters
node_converters -.->|"supplies results"| node_views
node_views -->|"compares assessments"| node_compare
node_views -->|"produces reports"| node_exports
node_frontend -->|"uses server state"| node_frontend_state
node_frontend_state -.->|"requests API"| node_evaluation_api
node_evaluation_api -->|"delegates to"| node_evaluation_service
node_evaluation_api -->|"checks permissions"| node_authz
node_evaluation_api -.->|"reads evaluations"| node_eval_store
node_evaluation_api -.->|"supports analysis"| node_tags_stats
node_authn -->|"validates users"| node_user_mgmt
node_authn -.->|"issues sessions"| node_user_store
node_user_mgmt -->|"manages users"| node_user_store
node_group_mgmt -->|"manages groups"| node_group_store
node_group_mgmt -->|"maintains owners"| node_user_mgmt
node_group_mgmt -->|"links evaluations"| node_evaluation_service
node_eval_store -.->|"persists in"| node_postgres
node_user_store -.->|"persists in"| node_postgres
node_group_store -.->|"persists in"| node_postgres
node_external_sources -->|"provides reports"| node_upload

click node_frontend "https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/App.vue"
click node_views "https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/views/Results.vue"
click node_compare "https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/views/Compare.vue"
click node_exports "https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/components/global/ExportHTMLModal.vue"
click node_frontend_state "https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/store/server.ts"
click node_upload "https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/components/global/upload_tabs/FileReader.vue"
click node_converters "https://github.com/mitre/heimdall2/blob/master/libs/hdf-converters/src/base-converter.ts"
click node_inspec "https://github.com/mitre/heimdall2/blob/master/libs/inspecjs/src/context.ts"
click node_evaluation_api "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluations.controller.ts"
click node_evaluation_service "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluations.service.ts"
click node_tags_stats "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/statistics/statistics.controller.ts"
click node_authn "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/authn/authn.service.ts"
click node_authz "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/casl/casl-ability.factory.ts"
click node_user_mgmt "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/users/users.service.ts"
click node_group_mgmt "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/groups/groups.service.ts"
click node_eval_store "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluation.model.ts"
click node_user_store "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/users/user.model.ts"
click node_group_store "https://github.com/mitre/heimdall2/blob/master/apps/backend/src/groups/group.model.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_frontend,node_views,node_compare,node_exports,node_frontend_state toneBlue
class node_upload,node_converters,node_inspec,node_postgres toneAmber
class node_evaluation_api,node_evaluation_service,node_tags_stats toneMint
class node_authn,node_authz,node_user_mgmt,node_group_mgmt toneRose
class node_eval_store,node_user_store,node_group_store,node_user,node_external_sources toneIndigo
```

## Components

### Review and reporting

- [Heimdall UI](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/App.vue): `apps/frontend/src/App.vue`
- [Review views](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/views/Results.vue): `apps/frontend/src/views/Results.vue`
- [Comparison view](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/views/Compare.vue): `apps/frontend/src/views/Compare.vue`
- [Report exports](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/components/global/ExportHTMLModal.vue): `apps/frontend/src/components/global/ExportHTMLModal.vue`
- [Frontend state and API](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/store/server.ts): `apps/frontend/src/store/server.ts`

### Ingestion and formats

- [Upload interfaces](https://github.com/mitre/heimdall2/blob/master/apps/frontend/src/components/global/upload_tabs/FileReader.vue): `apps/frontend/src/components/global/upload_tabs/FileReader.vue`
- [OHDF converters](https://github.com/mitre/heimdall2/blob/master/libs/hdf-converters/src/base-converter.ts): `libs/hdf-converters/src/base-converter.ts`
- [InSpec parsing](https://github.com/mitre/heimdall2/blob/master/libs/inspecjs/src/context.ts): `libs/inspecjs/src/context.ts`

### Backend API

- [Evaluation API](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluations.controller.ts): `apps/backend/src/evaluations/evaluations.controller.ts`
- [Evaluation service](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluations.service.ts): `apps/backend/src/evaluations/evaluations.service.ts`
- [Tags and statistics](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/statistics/statistics.controller.ts): `apps/backend/src/statistics/statistics.controller.ts`

### Identity and access

- [Authentication](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/authn/authn.service.ts): `apps/backend/src/authn/authn.service.ts`
- [Authorization](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/casl/casl-ability.factory.ts): `apps/backend/src/casl/casl-ability.factory.ts`
- [User management](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/users/users.service.ts): `apps/backend/src/users/users.service.ts`
- [Groups and sharing](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/groups/groups.service.ts): `apps/backend/src/groups/groups.service.ts`

### Persistent data

- [Evaluation records](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/evaluations/evaluation.model.ts): `apps/backend/src/evaluations/evaluation.model.ts`
- [User records](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/users/user.model.ts): `apps/backend/src/users/user.model.ts`
- [Group records](https://github.com/mitre/heimdall2/blob/master/apps/backend/src/groups/group.model.ts): `apps/backend/src/groups/group.model.ts`

### Other components

- **Assessor**
- **PostgreSQL**
- **External data sources**

## Connections

- Assessor → Heimdall UI: reviews (evidence: `README.md`)
- Heimdall UI → Upload interfaces: loads reports (evidence: `README.md`)
- Upload interfaces → OHDF converters: converts formats
- InSpec parsing → OHDF converters: parses InSpec
- OHDF converters → Review views: supplies results
- Review views → Comparison view: compares assessments (evidence: `README.md`)
- Review views → Report exports: produces reports (evidence: `README.md`)
- Heimdall UI → Frontend state and API: uses server state (evidence: `apps/frontend/src/App.vue`)
- Frontend state and API → Evaluation API: requests API
- Evaluation API → Evaluation service: delegates to (evidence: `apps/backend/src/evaluations/evaluations.controller.ts`)
- Evaluation API → Authorization: checks permissions (evidence: `apps/backend/src/evaluations/evaluations.controller.ts`)
- Evaluation API → Evaluation records: reads evaluations (evidence: `apps/backend/src/evaluations/evaluations.controller.ts`)
- Evaluation API → Tags and statistics: supports analysis
- Authentication → User management: validates users (evidence: `apps/backend/src/authn/authn.service.ts`)
- Authentication → User records: issues sessions (evidence: `apps/backend/src/authn/authn.service.ts`)
- User management → User records: manages users (evidence: `apps/backend/src/users/users.service.ts`)
- Groups and sharing → Group records: manages groups (evidence: `apps/backend/src/groups/groups.service.ts`)
- Groups and sharing → User management: maintains owners (evidence: `apps/backend/src/users/users.service.ts`)
- Groups and sharing → Evaluation service: links evaluations (evidence: `apps/backend/src/groups/groups.controller.ts`)
- Evaluation records → PostgreSQL: persists in
- User records → PostgreSQL: persists in
- Group records → PostgreSQL: persists in
- External data sources → Upload interfaces: provides reports (evidence: `README.md`)