# owasp/threat-dragon architecture

> Architecture diagram of the GitHub repository owasp/threat-dragon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/owasp/threat-dragon
- Repository: https://github.com/owasp/threat-dragon

## Overview

##### Main Components
- Back-End Server (td.server): This Node.js/Express back-end contains configuration (environment and security headers), a suite of controllers (for auth, threat model management, etc.), environmental integrations for external providers, and repository layers to communicate with external systems. It also contains unit and integration tests.
- External Services/Repositories: The integration modules (providers and repositories) support external data sources such as GitHub, Bitbucket, and GitLab. They are represented by dedicated directories and files (e.g., providers in td.server/src/providers, repositories in td.server/src/repositories).
- Container & Deployment Environment: Dockerfile, GitHub workflows, and related configuration files indicate that the system is containerized and integrated with CI/CD pipelines.
- Additional Libraries & Helpers: Various helper modules (for encryption, logging, JWT handling, etc.) and configuration settings (eslintrc, babel, etc.) support both front-end and back-end components.

##### Relationships and Data Flow
- The Front-End communicates with the Back-End server through RESTful API endpoints (documented in service/api modules in td.vue and configured on td.server).
- The Back-End processes and verifies data, handles authentication, performs threat modeling CRUD operations, accesses external repositories through provider modules, and returns responses to the front-end.
- External integrations are invoked by both the back-end (for repository/file management, third-party authentication) and sometimes even from the front-end (during OAuth flows).
- CI/CD pipelines, container builds, and Docker images connect to the deployment process, stressing the importance of automated testing (shown in td.server/test and td.vue/tests) and containerized runtime.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear split between the “td.vue” front-end and “td.server” back-end. Each has its own dependencies, tests, and service layers.
- Modularization: The project is organized into modules (controllers, providers, repositories, helpers for the back-end; components, views, store modules, services for the front-end), ensuring that changes in one area are isolated from others.
- Integration with External Platforms: The environment-specific provider modules (for GitHub, Bitbucket, GitLab, Google) show a pattern for pluggable integrations.
- Test-Driven Architecture: With extensive unit and end-to-end tests, the design ensures reliability and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend (td.vue)"
        F1["Vue.js Client"]:::frontend
        F2["UI Components/Views (Diagram Editor, Threat Reporting, OAuth)"]:::frontend
        F3["Helpers (Frontend)"]:::helper
        F1 -->|"uses"| F3
        F1 -->|"renders"| F2
    end

    %% Backend Subgraph
    subgraph "Backend (td.server)"
        B1["API Endpoints & Controllers"]:::backend
        B2["Helpers (Backend)"]:::helper
        B3["Integration Providers"]:::backend
        B4["Env Configuration"]:::backend
        B5["Repository Layer"]:::backend
        B1 -->|"calls_provider"| B3
        B1 -->|"uses_env"| B4
        B1 -->|"manages_models"| B5
        B1 -->|"utilizes"| B2
    end

    %% External and Data Storage Nodes
    E1["External Providers (GitHub,Bitbucket,GitLab,Google)"]:::external
    DS["Threat Model Files Storage"]:::external

    %% Deployment & Testing Subgraph
    subgraph "Deployment & Testing"
        D1["Dockerfile"]:::deployment
        D2["GitHub Workflows"]:::deployment
        T1["Tests (Unit & Integration)"]:::deployment
        D1 --> D2
    end

    %% Connections between major components
    F1 -->|"API_Call"| B1
    B3 -->|"integrates_with"| E1
    B5 -->|"stores_files"| DS

    %% CI/CD and Testing flows from Frontend and Backend to Deployment
    F1 -->|"deploys_via"| D1
    B1 -->|"deploys_via"| D1
    F1 -->|"tested_by"| T1
    B1 -->|"tested_by"| T1

    %% Click Events
    click F1 "https://github.com/owasp/threat-dragon/blob/main/td.vue"
    click B1 "https://github.com/owasp/threat-dragon/blob/main/td.server"
    click B3 "https://github.com/owasp/threat-dragon/tree/main/td.server/src/providers"
    click B4 "https://github.com/owasp/threat-dragon/tree/main/td.server/src/env"
    click B5 "https://github.com/owasp/threat-dragon/tree/main/td.server/src/repositories"
    click DS "https://github.com/owasp/threat-dragon/tree/main/ThreatDragonModels"
    click D1 "https://github.com/owasp/threat-dragon/tree/main/Dockerfile"
    click D2 "https://github.com/owasp/threat-dragon/tree/main/.github/workflows"
    click B2 "https://github.com/owasp/threat-dragon/tree/main/td.server/src/helpers"
    click F3 "https://github.com/owasp/threat-dragon/tree/main/td.vue/src/service"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef deployment fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef helper fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
