# troll-os/openex architecture

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

- Interactive diagram: https://gitdiagram.com/troll-os/openex
- Repository: https://github.com/troll-os/openex

## Overview

##### Project type and purpose
- This is a full-stack, monolithic web application designed for planning and conducting crisis exercises and adversary simulation (OpenEx).
- Backend is a Java Spring-Boot RESTful API (openex-api module), sharing domain model libraries (openex-model, openex-framework).
- Frontend is a React/TypeScript single-page application (openex-front) providing public, private and admin UIs.
- The platform supports scheduling (Quartz via Spring scheduler), migrations (Flyway), file storage (MinIO), email/SMS/social integrations, SSO (OIDC, SAML, OAuth2).

##### File structure
- Top-level modules:
- openex-api: Spring Boot application (controllers, services, scheduler, security, imports, injectors).
- openex-framework: shared execution framework and contract definitions for injectors.
- openex-model: JPA entities, repositories, converters, MinIO driver, custom validators.
- openex-front: React app with Yarn/Vite, split into public, private, admin sections; uses Redux actions and reducers.
- Dev tooling and deployment:
- Dockerfiles, docker-compose, CI/CD configs (.circleci, .github workflows, .drone.yml).
- Flyway migration scripts in resources/db/migration.

##### README for additional insights
- Tech stack: Java 17+ with Spring Boot, React 18+, TypeScript, Yarn 4, Docker.
- Integrations: OpenEx ecosystem (email providers, OpenCTI), SSO providers (OAuth2, OIDC, SAML).
- Editions: Community (Apache 2.0) and Enterprise (non-commercial).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (SPA)" 
        direction TB
        PUB_UI["React Public UI"]:::frontend
        PRI_UI["React Private UI"]:::frontend
        ADM_UI["React Admin UI"]:::frontend
        REDUX["Redux Actions & Reducers"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Spring Boot API)" 
        direction TB
        API["Spring Boot API"]:::backend
        CONT["API Controllers"]:::backend
        SRV["Service Layer"]:::backend
        SCHED["Scheduler & Jobs (Quartz)"]:::backend
        INJ["Injectors"]:::backend
        SEC_CFG["Security Config & Filters"]:::backend
        AOP["AOP Logging"]:::backend
        LIBS["Shared Libraries\n(openex-model & openex-framework)"]:::backend
    end

    %% Data Stores
    subgraph "Data & Storage"
        direction TB
        DB["PostgreSQL DB"]:::datastore
        MINIO["MinIO Storage"]:::datastore
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        EMAIL["Email Service"]:::external
        CTI["OpenCTI Connector"]:::external
        SSO["SSO Providers\n(OAuth2, OIDC, SAML)"]:::external
        OSM["OpenStreetMap Tiles"]:::external
    end

    %% DevOps / CI-CD
    subgraph "DevOps & CI/CD"
        direction TB
        DOCKER["Docker & Compose"]:::devops
        CICD["CI/CD Pipelines"]:::devops
    end

    %% Frontend to API
    PUB_UI -->|"HTTPS/REST"| API
    PRI_UI -->|"HTTPS/REST"| API
    ADM_UI -->|"HTTPS/REST"| API
    REDUX --> API

    %% API internal
    API --> CONT
    CONT --> SRV
    SRV --> DB
    SRV --> MINIO
    SRV --> EMAIL
    SRV --> CTI
    SRV --> SSO
    SRV --> OSM
    SRV --> INJ
    CONT --> SEC_CFG
    SRV --> AOP
    SRV --> SCHED
    API --> LIBS

    %% DevOps flows
    CICD --> DOCKER
    DOCKER --> API
    DOCKER --> DB
    DOCKER --> MINIO

    %% Click Events
    click API "https://github.com/troll-os/openex/tree/master/openex-api/src/main/java/io/openex"
    click CONT "https://github.com/troll-os/openex/tree/master/openex-api/src/main/java/io/openex/rest"
    click SRV "https://github.com/troll-os/openex/tree/master/openex-api/src/main/java/io/openex/service"
    click SCHED "https://github.com/troll-os/openex/tree/master/openex-api/src/main/java/io/openex/scheduler"
    click INJ "https://github.com/troll-os/openex/tree/master/openex-api/src/main/java/io/openex/injects"
    click SEC_CFG "https://github.com/troll-os/openex/blob/master/openex-api/src/main/java/io/openex/config/AppSecurityConfig.java"
    click AOP "https://github.com/troll-os/openex/tree/master/openex-api/src/main/java/io/openex/aop"
    click LIBS "https://github.com/troll-os/openex/tree/master/openex-framework/src/main/java/io/openex"
    click DB "https://github.com/troll-os/openex/tree/master/openex-model/src/main/java/io/openex/database/model"
    click MINIO "https://github.com/troll-os/openex/blob/master/openex-model/src/main/java/io/openex/driver/MinioDriver.java"
    click EMAIL "https://github.com/troll-os/openex/blob/master/openex-model/src/main/java/io/openex/config/MinioConfig.java"
    click PUB_UI "https://github.com/troll-os/openex/tree/master/openex-front/src/public"
    click PRI_UI "https://github.com/troll-os/openex/tree/master/openex-front/src/private"
    click ADM_UI "https://github.com/troll-os/openex/tree/master/openex-front/src/admin"
    click REDUX "https://github.com/troll-os/openex/tree/master/openex-front/src/actions"
    click DOCKER "https://github.com/troll-os/openex/tree/master/Dockerfile"
    click CICD "https://github.com/troll-os/openex/blob/master/.circleci/config.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#00ACC1
    classDef backend fill:#E8F5E9,stroke:#43A047
    classDef datastore fill:#FFF3E0,stroke:#FB8C00
    classDef external fill:#ECEFF1,stroke:#90A4AE
    classDef devops fill:#F3E5F5,stroke:#8E24AA
```
