# openbas-platform/openbas architecture

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

- Interactive diagram: https://gitdiagram.com/openbas-platform/openbas
- Repository: https://github.com/openbas-platform/openbas

## Overview

##### Project type & purpose
- This is a full-stack, modular platform (“OpenBAS”) for planning and running cyber-adversary simulations.
- It comprises:
- A Java Spring Boot backend (“openbas-api”)
- A React/TypeScript front-end SPA (“openbas-front”)
- A shared Java model layer (“openbas-model”)
- A framework module for common code (“openbas-framework”)
- Dev orchestration configs (Docker, docker-compose, CI/CD)

##### File-structure insights
- Top-level modules:
- openbas-api: monolithic REST API + scheduler + collectors + plugin-style executors/injectors
- openbas-front: React UI (public & private/admin), E2E tests
- openbas-model: data model + persistence + ES engine + drivers
- openbas-framework: shared abstractions (queues, contracts)
- openbas-dev: docker-compose definitions for multi-container local/development topology
- Backend layering:
- Controller (rest package) → Service → Repository (JPA/SQL, ES)
- AOP, security, caching, scheduling modules
- Asynchronous work via RabbitMQ (queue configs & helpers)
- Executors/injectors connect to external platforms (Caldera, CrowdStrike, email, SMS, Mastodon, OpenCTI…)
- Infra/config:
- application.properties, Flyway migrations, OTLP telemetry, Pyroscope
- Dockerfiles for containers, GitHub Actions/Drone/CircleCI

##### Key README points
- Platform edition (Community vs. Enterprise)
- Architecture: core modules + integrations with OpenCTI, message platforms, OpenStreetMap
- Deployment via Docker or manual (db, ES, RabbitMQ, Minio, OTLP collector)

- Front-end (React SPA + NGINX or static-file server)
- API Backend (Spring Boot monolith)
- Relational DB (PostgreSQL/MySQL)
- Search Engine (Elasticsearch)
- Object Store (Minio/S3)
- Message Broker (RabbitMQ)
- Telemetry Collector (OTel Collector + Pyroscope)
- External services:
– OpenCTI (threat intel)
– SMTP server (email)
– SMS provider (OVH)
– Social platform (Mastodon)
- Executors/Injectors (plugin workers)
- Browser → Front-end (HTTP/S)
- Front-end → API (REST calls, WebSocket/SSE for live updates)
- API ↔ DB (JPA)
- API ↔ ES via openbas-model (for full-text search)
- API ↔ Minio (file uploads: agents, implants)
- API → RabbitMQ (publish tasks & scheduling triggers)
- Executors subscribe to RabbitMQ → perform platform-specific work → send results back via API or RabbitMQ
- API → Telemetry Collector (OTLP) → Pyroscope storage
- API ↔ External services (OpenCTI, SMTP, SMS, Mastodon)
c. Architectural patterns & principles:
- Layered monolith (Controller→Service→Repository)
- Modular design with plugin-style executors/injectors
- Event-driven asynchronous tasks over RabbitMQ
- Shared model and framework modules reused across API and executors
- Configuration-driven (Spring profiles, Docker)
d. Technologies & frameworks:
- Front-end: React, Redux, Yarn v4, Vite/Vitest, Playwright
- Backend: Java 17+, Spring Boot, Spring Security, Flyway, AOP, OpenTelemetry
- DB: SQL (Postgres/MySQL), JPA/Hibernate
- Search: Elasticsearch via custom driver
- Object storage: Minio (S3 API)
- Broker: RabbitMQ
- Telemetry: OTel Collector, Pyroscope
- CI/CD: GitHub Actions, Drone, CircleCI, Docker

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser"]:::external
        Frontend["React SPA\n(NGINX)"]:::frontend
        Browser -->|"HTTP/S"| Frontend
    end
    click Frontend "https://github.com/openbas-platform/openbas/tree/master/openbas-front/"

    %% Backend Layer
    subgraph "API Backend" 
        direction TB
        API["Spring Boot Monolith\n(openbas-api)"]:::api
        subgraph "Layered Modules"
            direction TB
            Controllers["Controllers"]:::api
            Services["Services"]:::api
            Repositories["Repositories"]:::api
        end
        AOP["AOP (logging, security)"]:::api
        Security["Security Config"]:::api
        Caching["Caching Config"]:::api
        Scheduling["Scheduler & Collectors"]:::api
        Executors["Executors\n(plugin workers)"]:::worker
        Injectors["Injectors\n(plugin tasks)"]:::worker
        API --> Controllers
        Controllers --> Services
        Services --> Repositories
        Controllers --> AOP
        Controllers --> Security
        Services --> Caching
        Services --> Scheduling
        Scheduling --> Executors
        Scheduling --> Injectors
    end
    click API "https://github.com/openbas-platform/openbas/tree/master/openbas-api/"
    click Controllers "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/rest/"
    click Services "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/service/"
    click Repositories "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/database/repository/"
    click AOP "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/aop/"
    click Security "https://github.com/openbas-platform/openbas/blob/master/openbas-api/src/main/java/io/openbas/config/AppSecurityConfig.java"
    click Caching "https://github.com/openbas-platform/openbas/blob/master/openbas-api/src/main/java/io/openbas/config/cache/CachingConfig.java"
    click Scheduling "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/scheduler/"
    click Executors "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/executors/"
    click Injectors "https://github.com/openbas-platform/openbas/tree/master/openbas-api/src/main/java/io/openbas/injectors/"

    Frontend -->|"REST / WebSocket"| API

    %% Shared Modules
    subgraph "Shared Modules"
        direction TB
        Model["openbas-model"]:::framework
        Framework["openbas-framework"]:::framework
    end
    click Model "https://github.com/openbas-platform/openbas/tree/master/openbas-model/"
    click Framework "https://github.com/openbas-platform/openbas/tree/master/openbas-framework/"

    API -->|"JPA (SQL)"| DB
    API -->|"ES API"| ES
    API -->|"S3 API"| Minio
    API -->|"AMQP"| RabbitMQ
    API -->|"OTLP"| Telemetry
    API -->|"HTTP"| OpenCTI
    API -->|"SMTP"| SMTP
    API -->|"SMS API"| SMS
    API -->|"Mastodon API"| Mastodon

    %% Infrastructure
    subgraph "Infrastructure Services"
        direction TB
        DB["PostgreSQL/MySQL"]:::datastore
        ES["Elasticsearch"]:::datastore
        Minio["Minio (S3)"]:::datastore
        RabbitMQ["RabbitMQ"]:::broker
        Telemetry["OTel Collector\n+ Pyroscope"]:::datastore
        OpenCTI["OpenCTI"]:::external
        SMTP["SMTP Server"]:::external
        SMS["SMS Provider"]:::external
        Mastodon["Mastodon"]:::external
    end
    click DB "https://github.com/openbas-platform/openbas/tree/master/openbas-model/"
    click ES "https://github.com/openbas-platform/openbas/blob/master/openbas-model/src/main/java/io/openbas/engine/EsEngine.java"
    click Minio "https://github.com/openbas-platform/openbas/blob/master/openbas-model/src/main/java/io/openbas/driver/MinioDriver.java"
    click RabbitMQ "https://github.com/openbas-platform/openbas/blob/master/openbas-framework/src/main/java/io/openbas/config/RabbitmqConfig.java"
    click Telemetry "https://github.com/openbas-platform/openbas/blob/master/openbas-dev/otlp-config.yaml"
    click OpenCTI "https://github.com/openbas-platform/openbas/blob/master/openbas-dev/docker-compose.yml"
    click SMTP "https://github.com/openbas-platform/openbas/blob/master/openbas-dev/docker-compose.yml"
    click SMS "https://github.com/openbas-platform/openbas/blob/master/openbas-dev/docker-compose.yml"
    click Mastodon "https://github.com/openbas-platform/openbas/blob/master/openbas-dev/docker-compose.yml"

    %% Workers subscribe to RabbitMQ
    Executors -->|subscribe| RabbitMQ
    Injectors -->|subscribe| RabbitMQ
    RabbitMQ -->|task results| API

    %% Orchestration & CI/CD
    subgraph "Dev & CI/CD"
        direction TB
        DockerCompose["Docker Compose\n(openbas-dev)"]:::infra
        GitHubActions["GitHub Actions"]:::infra
        CircleCI["CircleCI"]:::infra
        Drone["Drone CI"]:::infra
    end
    click DockerCompose "https://github.com/openbas-platform/openbas/blob/master/openbas-dev/docker-compose.yml"
    click GitHubActions "https://github.com/openbas-platform/openbas/tree/master/.github/workflows/"
    click CircleCI "https://github.com/openbas-platform/openbas/blob/master/.circleci/config.yml"
    click Drone "https://github.com/openbas-platform/openbas/blob/master/.drone.yml"

    %% Click shared configs
    click Framework "https://github.com/openbas-platform/openbas/tree/master/openbas-framework/"
    click Model "https://github.com/openbas-platform/openbas/tree/master/openbas-model/"

    classDef frontend fill:#3b82f6,stroke:#1e40af,color:#fff
    classDef api fill:#10b981,stroke:#065f46,color:#fff
    classDef datastore fill:#f59e0b,stroke:#b45309,color:#000
    classDef broker fill:#eab308,stroke:#a16207,color:#000
    classDef worker fill:#8b5cf6,stroke:#5b21b6,color:#fff
    classDef external fill:#6b7280,stroke:#374151,color:#fff
    classDef framework fill:#6366f1,stroke:#4338ca,color:#fff
    classDef infra fill:#14b8a6,stroke:#0d9488,color:#fff
```
