# thehive-project/thehive architecture

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

- Interactive diagram: https://gitdiagram.com/thehive-project/thehive
- Repository: https://github.com/thehive-project/thehive

## Overview

##### Main Components
- Core Backend Engine (TheHive Server)
- This is implemented in Scala and spans multiple directories (for example, the “thehive” folder with controllers, models, and services and the “app” directory).
- It houses business logic such as case management, task handling, observables, notifications, and multi-tenancy.
- Frontend Web Application
- Found in the “frontend” directory, which contains client-side assets (HTML, CSS, JavaScript, components, and views).
- This component handles user interaction and presentation.
- Client Libraries and APIs
- “client-common” and “client” directories indicate reusable client components and likely API client implementations (thehive4py is also mentioned in the README).
- External Integration/Connector Modules
- “cortex” and “misp” directories include connectors for Cortex (for analysis of observables) and MISP (for incident/event integration) respectively.
- Other integration modules (such as DigitalShadows2TH and Zerofox2TH referenced in the README) might be represented externally.
- DTOs & Migration Modules
- Directories like “dto”, “cortex/dto”, and “migration” manage data transfer objects and data migration for legacy or evolving schemas.
- Build and Configuration Components
- Several configuration files (e.g., in “conf”, “project”, “docker”, “misp/connector/src/main/resources”, etc.) and build scripts (e.g., build.sbt) signify that deployment and runtime configurations are essential to the architecture.

##### Relationships and Interactions
- The Core Backend is structured in an MVC or modular service pattern – controllers receive HTTP requests, pass them on to services, and interact with data models.
- The Core Backend also communicates with external systems via the integration/connector modules. For instance:
- The MISP Connector integrates inbound events and exports investigations back to MISP.
- The Cortex Connector allows the platform to spawn analyzers or responder actions on observables.
- The DTO and migration modules serve to decouple the internal data representation from external interfaces or legacy systems.
- There is a clear separation along authentication, authorization (RBAC), multi-tenancy, and notification systems. Represent these as supporting infrastructure modules linked to the core engine.

##### Architectural Patterns and Design Principles
- Modular and Pluggable Architecture: With clearly separated connectors (for Cortex and MISP), the platform supports adding or swapping external integrations.
- MVC or Layered Pattern: The relationship between controllers, services, and data models can be depicted in a layer-based approach inside the backend.
- Multi-tier Architecture: Different tiers (frontend, backend, connectors, external integration) interact via clearly defined interfaces.

##### Relevant Technologies and Frameworks
- Scala as the primary programming language for the backend.
- Play Framework might be in use (hinted by “conf/play” and reference configuration files) for handling HTTP routes and API controllers.
- Frontend technologies (AngularJS or similar frameworks, as seen from the structure in “frontend/app/scripts”).
- Integration with MISP and Cortex is highlighted; consider noting that Cortex analyzers/responder services are external microservices.
- Build tools like SBT drive the Scala build process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User Browser"]:::external
    B["Frontend Web Application"]:::frontend
    A -->|"HTTPREST"| B
    click B "https://github.com/thehive-project/thehive/tree/main/frontend/"
    
    C["TheHive Core Backend"]:::backend
    B -->|"RESTAPI"| C
    click C "https://github.com/thehive-project/thehive/tree/main/thehive/"
    
    D["Core Server Code"]:::backend
    C -->|"InternalCall"| D
    click D "https://github.com/thehive-project/thehive/tree/main/app/"

    subgraph "Backend Modules"
        E["Controllers"]:::backend
        F["Services"]:::backend
        G["Data Models"]:::backend
        E -->|"calls"| F
        F -->|"processes"| G
    end
    C -->|"routesTo"| E

    subgraph "Client Libraries & APIs"
        I["Client Common"]:::backend
        click I "https://github.com/thehive-project/thehive/tree/main/client-common/"
        J["API Client"]:::backend
        click J "https://github.com/thehive-project/thehive/tree/main/client/"
        I -->|"supports"| J
    end
    C -->|"utilizes"| I

    subgraph "Integration Connectors"
        K["MISP Connector"]:::integrations
        click K "https://github.com/thehive-project/thehive/tree/main/misp/"
        L["Cortex Connector"]:::integrations
        click L "https://github.com/thehive-project/thehive/tree/main/cortex/"
        K -->|"forwards"| L
    end
    C -->|"integratesWith"| K
    C -->|"integratesWith"| L

    subgraph "DTO & Migration"
        M["DTO Layer (TheHive)"]:::dto
        click M "https://github.com/thehive-project/thehive/tree/main/dto/"
        N["Cortex DTO"]:::dto
        click N "https://github.com/thehive-project/thehive/tree/main/cortex/dto/"
        O["Migration Module"]:::dto
        click O "https://github.com/thehive-project/thehive/tree/main/migration/"
        M -->|"migratesTo"| O
        N -->|"migratesTo"| O
    end
    E -->|"transfersData"| M

    subgraph "Build & Configuration"
        P["Configuration Files"]:::supporting
        click P "https://github.com/thehive-project/thehive/tree/main/conf/"
        Q["Build Configurations"]:::supporting
        click Q "https://github.com/thehive-project/thehive/tree/main/project/"
        R["SBT Build"]:::supporting
        click R "https://github.com/thehive-project/thehive/blob/main/build.sbt"
        S["Docker Config"]:::supporting
        click S "https://github.com/thehive-project/thehive/tree/main/docker/"
        P -->|"defines"| Q
        Q -->|"triggers"| R
        R -->|"packagesInto"| S
    end

    T["External Systems"]:::integrations
    T -->|"exposesMISPAPIs"| K
    T -->|"exposesCortexAPIs"| L

    classDef frontend fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef integrations fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef dto fill:#d0e6f7,stroke:#333,stroke-width:2px;
    classDef supporting fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#fdfd96,stroke:#333,stroke-width:2px;
```
