# opfab/operatorfabric-core architecture

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

- Interactive diagram: https://gitdiagram.com/opfab/operatorfabric-core
- Repository: https://github.com/opfab/operatorfabric-core

## Overview

##### Project Type and Purpose
- OperatorFabric is a full-stack, microservices-based platform for real-time operational event management in utility control centers.
- It provides REST/Kafka endpoints, templating, calendar/timeline UIs, archives, notifications, and integration with external authentication (OAuth2/Keycloak), Prometheus monitoring, and CLI tooling.

##### High-Level Architecture Components
a. User Interface Layer
- Angular SPA (“ui/main”) served via Nginx or embedded Angular server
- Provides screens (feed, calendar, archives, admin, external-app iframe) and consumes backend REST/Kafka event streams
b. API & Authentication
- OAuth2 / OpenID Connect via Keycloak (config/keycloak)
- WebSecurityConfiguration in each Spring Boot service enforces JWT-based auth
c. Backend Microservices (Java/Spring Boot)
- users – user/group/permission management, MongoDB storage
- businessconfig – stores UI templates, CSS, i18n bundles in file volumes
- cards-publication – consumes “cardCommand” Avro over Kafka, processes/publishes cards, MongoDB storage, response producer
- cards-consultation – WebFlux service serving live card FF over REST & SSE, MongoDB repository
- external-devices – CRUD on device configs, drivers (Modbus), MongoDB
- supervisor – monitors real-time connections, heartbeat, MongoDB
d. Auxiliary Node.js Services
- cards-reminder – schedule reminders via rrule, interfaces with MongoDB and email
- cards-external-diffusion – controls diffusion rates, routing, mail templating via Handlebars
- common – shared Node.js utilities (event bus client, JWT utils)
e. Eventing & Messaging
- Kafka topics for card commands (Avro)
- RabbitMQ (tools/generic/utilities/eventbus) optionally for inter-service events
f. Data Stores
- MongoDB per microservice (config in docker-volumes under services/*/src/main/docker/volume)
- Avro schemas in client modules (client/cards, etc.)
g. CLI & Tooling
- opfab-docker-cli (cli/src) for scripting admin tasks
- bin/ scripts for local development, CI (startOpfab.sh, launch tests)
- tooling/, tools/ for migrations, testing, swagger generation, monitoring
h. CI/CD & Monitoring
- GitHub Actions workflows under .github/workflows
- Gradle multi-module build (build.gradle, settings.gradle)
- Prometheus configured in bin/monitoring (prometheus.yml)
- Scorecards, WhiteSource, SonarCloud integrations

##### Interactions & Data Flows
- Users ↔ UI (HTTP/HTTPS)
- UI ↔ Backend services (REST/SSE)
- Backend services ↔ MongoDB (read/write)
- cards-publication ↔ Kafka (consume card commands, produce response cards)
- Node.js reminder/diffusion services ↔ Backend services (HTTP client & DB)
- Services ↔ RabbitMQ event bus (broadcast internal events)
- Services ↔ Keycloak (OAuth2 token introspection)
- bin/ scripts ↔ Docker Compose (spin up all containers)

##### Architectural Patterns & Principles
- Microservices: each bounded context as independent Spring Boot app
- Event-driven: Kafka for domain events, RabbitMQ for cross-service events
- Hexagonal/Ports & Adapters in services (controllers, services, repositories)
- API Gateway pattern implicit via UI’s direct calls to multiple services
- Shared libraries (tools/generic, tools/spring) for cross-cutting concerns
- Configuration-as-code: YAML in config/services, config/web-ui

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["Angular SPA"]:::frontend
    end
    click UI "https://github.com/opfab/operatorfabric-core/tree/develop/ui/main"

    %% Authentication
    Keycloak["Keycloak (OAuth2/OIDC)"]:::external
    click Keycloak "https://github.com/opfab/operatorfabric-core/tree/develop/config/keycloak"

    %% Java Microservices
    subgraph "Java Microservices"
        users["users"]:::java
        businessconfig["businessconfig"]:::java
        cardsPub["cards-publication"]:::java
        cardsCons["cards-consultation"]:::java
        externalDev["external-devices"]:::java
        supervisor["supervisor"]:::java
    end
    click users "https://github.com/opfab/operatorfabric-core/tree/develop/services/users/src/main"
    click businessconfig "https://github.com/opfab/operatorfabric-core/tree/develop/services/businessconfig/src/main"
    click cardsPub "https://github.com/opfab/operatorfabric-core/tree/develop/services/cards-publication/src/main"
    click cardsCons "https://github.com/opfab/operatorfabric-core/tree/develop/services/cards-consultation/src/main"
    click externalDev "https://github.com/opfab/operatorfabric-core/tree/develop/services/external-devices/src/main"
    click supervisor "https://github.com/opfab/operatorfabric-core/tree/develop/services/supervisor/src/main"

    %% Node.js Services
    subgraph "Node.js Services"
        common["common"]:::node
        reminder["cards-reminder"]:::node
        diffusion["cards-external-diffusion"]:::node
    end
    click common "https://github.com/opfab/operatorfabric-core/tree/develop/node-services/common/src/common"
    click reminder "https://github.com/opfab/operatorfabric-core/tree/develop/node-services/cards-reminder/src"
    click diffusion "https://github.com/opfab/operatorfabric-core/tree/develop/node-services/cards-external-diffusion/src"

    %% Brokers
    subgraph "Event Brokers"
        Kafka["Kafka Broker"]:::broker
        RabbitMQ["RabbitMQ Broker"]:::broker
    end

    %% Databases
    subgraph "Databases"
        DB_users["MongoDB (users)"]:::db
        DB_bc["MongoDB (businessconfig)"]:::db
        DB_pub["MongoDB (cards-publication)"]:::db
        DB_cons["MongoDB (cards-consultation)"]:::db
        DB_ext["MongoDB (external-devices)"]:::db
        DB_sup["MongoDB (supervisor)"]:::db
    end

    %% CLI and Docker Compose
    CLI["CLI Tool"]:::tool
    click CLI "https://github.com/opfab/operatorfabric-core/tree/develop/cli/src"

    DockerCompose["Docker Compose"]:::infra
    click DockerCompose "https://github.com/opfab/operatorfabric-core/blob/develop/config/docker-compose.yml"

    %% CI/CD
    GH["GitHub Actions"]:::tool
    click GH "https://github.com/opfab/operatorfabric-core/tree/develop/.github/workflows"
    Gradle["Gradle Build"]:::tool

    %% Monitoring
    subgraph "Monitoring"
        Prom["Prometheus"]:::monitor
        click Prom "https://github.com/opfab/operatorfabric-core/blob/develop/bin/monitoring/prometheus.yml"
        Graf["Grafana"]:::monitor
    end

    %% UI interactions
    UI -->|HTTP/HTTPS| users
    UI -->|HTTP/HTTPS| businessconfig
    UI -->|HTTP/HTTPS| cardsPub
    UI -->|HTTP/HTTPS| cardsCons
    UI -->|HTTP/HTTPS| externalDev
    UI -->|HTTP/HTTPS| supervisor

    %% Service auth
    users -.->|dotted| Keycloak
    businessconfig -.->|dotted| Keycloak
    cardsPub -.->|dotted| Keycloak
    cardsCons -.->|dotted| Keycloak
    externalDev -.->|dotted| Keycloak
    supervisor -.->|dotted| Keycloak

    %% Databases connections
    users -->|gray| DB_users
    businessconfig -->|gray| DB_bc
    cardsPub -->|gray| DB_pub
    cardsCons -->|gray| DB_cons
    externalDev -->|gray| DB_ext
    supervisor -->|gray| DB_sup

    %% Kafka events
    cardsPub -->|dashed orange| Kafka
    Kafka -->|dashed orange| cardsPub

    %% RabbitMQ events
    users -->|dashed teal| RabbitMQ
    businessconfig -->|dashed teal| RabbitMQ
    cardsPub -->|dashed teal| RabbitMQ
    cardsCons -->|dashed teal| RabbitMQ
    externalDev -->|dashed teal| RabbitMQ
    supervisor -->|dashed teal| RabbitMQ

    %% Node.js service interactions
    reminder -->|gray| DB_pub
    diffusion -->|gray| DB_pub
    reminder -->|HTTP| cardsPub
    diffusion -->|HTTP| cardsPub
    common --> reminder
    common --> diffusion

    %% CLI and Docker Compose
    CLI -->|HTTP| users
    CLI -->|HTTP| businessconfig
    DockerCompose --> UI
    DockerCompose --> Kafka
    DockerCompose --> RabbitMQ
    DockerCompose --> users
    DockerCompose --> businessconfig
    DockerCompose --> cardsPub
    DockerCompose --> cardsCons
    DockerCompose --> externalDev
    DockerCompose --> supervisor

    %% CI/CD flow
    GH --> Gradle
    Gradle -->|build images| DockerCompose

    %% Monitoring connections
    users --> Prom
    businessconfig --> Prom
    cardsPub --> Prom
    cardsCons --> Prom
    externalDev --> Prom
    supervisor --> Prom
    Prom --> Graf

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#0288D1
    classDef java fill:#D5E8D4,stroke:#82B366
    classDef node fill:#FFF2CC,stroke:#D6B656
    classDef broker fill:#FFE6CC,stroke:#F57C00
    classDef db fill:#F2F2F2,stroke:#888
    classDef external fill:#E1D5E7,stroke:#9673A6
    classDef tool fill:#E1E0F8,stroke:#5B6EAE
    classDef infra fill:#ECECEC,stroke:#999
    classDef monitor fill:#F4E1A1,stroke:#BF9000
```
