# wkspower/wks-platform architecture

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

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

## Overview

##### Project Type and Purpose
- WKS Platform is an open-source, full-stack solution focused on case management and process automation. It implements a multi-tenant architecture supporting industries such as financial services, healthcare, insurance, and more.
- It leverages a diverse set of technologies and frameworks including Spring Boot for the backend, React for the frontend, Camunda for BPM engine integration, MongoDB for data persistence, Keycloak for identity and access management, Traefik for routing, MinIO for object storage, OPA for policy enforcement, and Form.io for dynamic form creation.

##### High-Level Architectural Components
- Backend Services – Implemented in Java (Spring Boot) and split into various microservices (found under apps/java/services):
▪ Case Engine REST API which exposes functionality for case management, process instance handling, and record operations.
▪ External task processing services (both Camunda 7 and Camunda 8 versions) handling asynchronous tasks.
▪ Demo Data Loader service that seeds or configures data.
▪ Storage API service that interfaces with MinIO, DigitalOcean, and other object storage drivers.
- Core Libraries – Modular Java libraries (under apps/java/libraries) that include:
▪ API-Security, BPM Engine interfaces, client libraries (for Camunda and other BPM engines), and case engine business logic.
▪ These serve as the backbone for the domain logic and provide shared functionality across services.
- Middleware & External Integrations:
▪ Camunda BPM engines (Camunda 7 and Camunda 8) for process automation.
▪ MongoDB for data persistence.
▪ Keycloak for IAM and enforcing Zero Trust security principles.
▪ Traefik serving as the reverse proxy and load balancer.
▪ OPA (Open Policy Agent) for enforcing fine-grained security and business rules.
▪ Kafka integrations for external messaging (evident from the Kafka producer/consumer modules within the Java services).
▪ Form.io integration for creating dynamic forms.
- Node.js-based Services – Complementary Node apps provide additional functionalities such as:
▪ Email Sender, Novu Publisher, and Websocket Publisher for messaging and notifications.

##### Relationships and Interactions
▪ For frontend vs backend: Show React-based UIs communicating via REST (or WebSockets) to the backend APIs.
▪ Backend microservices communicate internally using domain libraries and interact with backend external systems (e.g., Camunda, MongoDB, Kafka, Keycloak, MinIO).
- Multi-tenancy aspects by including an abstraction layer (or a notation) around the core services to indicate tenant isolation.

##### Architectural Patterns, Design, and Key Technologies
- Microservices – The backend is divided into well-defined services, each responsible for a specific domain (case engine, external tasks, storage, etc.).
- Layered Architecture – The system is organized into presentation (React), business logic (Spring Boot services backed by shared libraries), and data layers (MongoDB).
- Integration Patterns – Use messaging patterns (show Kafka producers/consumers) and API gateways (via Traefik) to manage external and cross-service communications.
- Containerization & Deployment – With multiple Dockerfiles and docker-compose configurations, highlight that the entire system is containerized for orchestration and scalability.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend
    subgraph "Frontend"
        CP["Case Portal (React)"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        REST["Case Engine REST API (Spring Boot)"]:::backend
        EXT7["External Task Processing (Camunda 7)"]:::backend
        EXT8["External Task Processing (Camunda 8)"]:::backend
        DDL["Demo Data Loader Service"]:::backend
        STORAGE["Storage API Service"]:::backend
    end

    %% Core Libraries
    subgraph "Core Libraries"
        APIS["API Security Module"]:::library
        BPMC["BPM Engine Client"]:::library
        BPMI["BPM Engine Interface"]:::library
        C7CL["Camunda 7 Client"]:::library
        C8CL["Camunda 8 Client"]:::library
        CEL["Case Engine Business Logic"]:::library
    end

    %% Node.js Services
    subgraph "Node.js Services"
        EMAIL["Email Sender"]:::nodejs
        NOVU["Novu Publisher"]:::nodejs
        WS["Websocket Publisher"]:::nodejs
    end

    %% External Systems
    subgraph "External Systems"
        CAM7["Camunda BPM Engine 7"]:::external
        CAM8["Camunda BPM Engine 8"]:::external
        MONGO["MongoDB"]:::external
        KC["Keycloak"]:::external
        MINIO["MinIO"]:::external
        KAFKA["Kafka"]:::external
        OPA["OPA"]:::external
        FORMIO["Form.io"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        TRAEFIK["Traefik (Reverse Proxy)"]:::infra
    end

    %% Relationships

    %% Infrastructure routes traffic to Frontend and Backend
    TRAEFIK -->|"Routes"| CP
    TRAEFIK -->|"Routes"| REST

    %% Frontend interactions
    CP -->|"REST"| REST
    CP -->|"DynamicForms"| FORMIO
    CP -->|"Auth"| KC

    %% Backend interactions
    REST -->|"Uses"| CEL
    REST -->|"SecuredBy"| APIS
    REST -->|"DataStore"| MONGO
    REST -->|"Events"| KAFKA
    REST -->|"BPMClient"| BPMC
    REST -->|"BPMInterface"| BPMI

    EXT7 -->|"UsesClient"| C7CL
    EXT7 -->|"Processes"| CAM7

    EXT8 -->|"UsesClient"| C8CL
    EXT8 -->|"Processes"| CAM8

    DDL -->|"SeedsData"| MONGO

    STORAGE -->|"StoresFiles"| MINIO

    APIS -->|"IntegratesWith"| KC
    APIS -->|"Enforces"| OPA

    %% Kafka events to Node.js Services
    KAFKA -->|"Message"| EMAIL
    KAFKA -->|"Message"| NOVU
    KAFKA -->|"Message"| WS

    %% Class Definitions
    classDef frontend fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef backend fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef library fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef nodejs fill:#FADBD8,stroke:#333,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#333,stroke-width:2px;
    classDef infra fill:#D2B4DE,stroke:#333,stroke-width:2px;

    %% Click Events
    click CP "https://github.com/wkspower/wks-platform/tree/develop/apps/react/case-portal"
    click REST "https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/case-engine-rest-api"
    click EXT7 "https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/c7-external-tasks"
    click EXT8 "https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/c8-external-tasks"
    click DDL "https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/demo-data-loader"
    click STORAGE "https://github.com/wkspower/wks-platform/tree/develop/apps/java/services/storage-api"
    click APIS "https://github.com/wkspower/wks-platform/tree/develop/apps/java/libraries/api-security"
    click BPMC "https://github.com/wkspower/wks-platform/tree/develop/apps/java/libraries/bpm-engine-client"
    click BPMI "https://github.com/wkspower/wks-platform/tree/develop/apps/java/libraries/bpm-engine-interface"
    click C7CL "https://github.com/wkspower/wks-platform/tree/develop/apps/java/libraries/c7-client"
    click C8CL "https://github.com/wkspower/wks-platform/tree/develop/apps/java/libraries/c8-client"
    click CEL "https://github.com/wkspower/wks-platform/tree/develop/apps/java/libraries/case-engine"
    click EMAIL "https://github.com/wkspower/wks-platform/tree/develop/apps/node/email-sender"
    click NOVU "https://github.com/wkspower/wks-platform/tree/develop/apps/node/novu-publisher"
    click WS "https://github.com/wkspower/wks-platform/tree/develop/apps/node/websocket-publisher"
```
