# m-elhamlaoui/keplereum architecture

> Architecture diagram of the GitHub repository m-elhamlaoui/keplereum, 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/m-elhamlaoui/keplereum
- Repository: https://github.com/m-elhamlaoui/keplereum

## Overview

##### Project Type and Purpose
- This is a full-stack, blockchain-backed, microservices architecture with:
– A React.js front-end for real-time monitoring (satellite positions, blockchain txns, metrics).
– Multiple Spring Boot & Go microservices (Satellite, Blockchain, User/GroundStation, Config Server, Discovery Server, API Gateway).
– A monolithic JHipster backend for domain data.
– Ethereum blockchain nodes (Geth), smart contracts (Solidity), and a Go-based WebSocket gateway.
– DevOps infrastructure: Docker, Kubernetes, Jenkins CI/CD, Prometheus/Grafana, ELK logging.

##### Main Components
2.1 User Interface Layer (Frontend)
– React App (runs in browser)
– WebSocket connection to Blockchain_WebSocket_Gateway
– REST calls to apiGateway
2.2 Edge/API Layer
– apiGateway (Spring Cloud Gateway or Zuul)
– SecurityConfig, JwtAuthenticationFilter
2.3 Service Registry & Configuration
– DiscoveryServer (Eureka)
– ConfigServer (Spring Cloud Config)
2.4 Microservices
– Satellites_Service (Spring Boot)
– User_GroundStation_Service (Spring Boot, JWT auth)
– Blockchain_Service (Spring Boot + Web3j, interacts with Ethereum)
– (Optional) Monitoring Service & Logging Service (if separate)
2.5 Monolithic Backend (JHipster)
– BackendApp, REST resources, domain, repository layers
– PostgreSQL, Elasticsearch, Liquibase migrations
2.6 Blockchain Infrastructure
– Ethereum Geth cluster (docker-compose, load balancer)
– Smart contracts deployed (SatelliteSystem.abi/bin)
2.7 WebSocket Gateway
– Go service that listens for blockchain events and pushes via WebSocket
2.8 Data Stores & External Systems
– PostgreSQL instances (per service or shared?)
– Elasticsearch (search, analytics)
– Prometheus & Grafana (metrics)
– ELK (Elasticsearch, Logstash, Kibana) for logs
– Zipkin (distributed tracing)
2.9 DevOps & Infrastructure
– Jenkins CI/CD pipelines
– Docker images & Kubernetes cluster
– Terraform/Ansible IaC

##### Relationships & Data Flows
- Browser → apiGateway (HTTPS REST) → discovery → microservice → database
- Browser ← WebSocket → Blockchain_WebSocket_Gateway ← Ethereum events
- Microservices ← ConfigServer (externalized configuration)
- Microservices ←→ DiscoveryServer (service registration/discovery)
- Blockchain_Service → Ethereum (via Web3j RPC)
- Geth cluster ←→ mining nodes (Go scripts)
- All services → Prometheus (metrics endpoint)
- All services → ELK (centralized logs)
- Jenkins → Docker build → Kubernetes deploy

##### Architectural Patterns & Principles
- Microservices registered in a service registry (Eureka) behind a single entry point (API Gateway).
- Externalized config via ConfigServer, supports multiple environments.
- Event-driven updates via WebSocket for real-time dashboard.
- Smart contract layer on public Ethereum, accessed via Web3j.
- Domain layer separation in JHipster monolith (Controllers, Services, Repositories).
- Infrastructure as Code for reproducible deployments.
- Monitoring & logging baked into containers for observability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        React["React Frontend"]:::frontend
    end

    %% Edge/API Layer
    subgraph "Edge/API Layer"
        apiGateway["API Gateway\n(Spring Cloud Gateway)"]:::edge
    end

    %% Service Registry & Config
    subgraph "Service Registry & Config"
        Discovery["Discovery Server\n(Eureka)"]:::service
        ConfigServer["Config Server\n(Spring Cloud Config)"]:::service
    end

    %% Microservices Layer
    subgraph "Microservices"
        Satellites["Satellites Service\n(Spring Boot)"]:::service
        UserService["User/GroundStation Service\n(Spring Boot)"]:::service
        BlockchainService["Blockchain Service\n(Spring Boot + Web3j)"]:::service
    end

    %% Monolithic Backend
    subgraph "Monolithic Backend"
        Monolith["JHipster Backend\n(BackendApp)"]:::monolith
        Postgres["PostgreSQL"]:::database
        ES_Mono["Elasticsearch"]:::database
    end

    %% Blockchain Infrastructure
    subgraph "Blockchain Infra"
        Geth["Geth Node Cluster"]:::infra
        SmartContracts["Smart Contracts\n(SatelliteSystem)"]:::infra
        WSGateway["WebSocket Gateway\n(Go Service)"]:::infra
    end

    %% DevOps & Observability
    subgraph "DevOps & Observability"
        Jenkins["Jenkins CI/CD"]:::infra
        Kubernetes["Kubernetes Cluster"]:::infra
        DockerReg["Docker Registry"]:::infra
        PromGrafana["Prometheus & Grafana"]:::monitor
        ELK["ELK Logging"]:::monitor
    end

    %% Relationships
    React -->|"REST/JSON"| apiGateway
    React -->|"WebSocket"| WSGateway
    apiGateway -->|"register with"| Discovery
    apiGateway -->|"fetch config"| ConfigServer
    apiGateway -->|"route REST"| Satellites
    apiGateway -->|"route REST"| UserService
    apiGateway -->|"route REST"| BlockchainService

    Satellites -->|"JDBC/SQL"| Postgres
    UserService -->|"JDBC/SQL"| Postgres
    BlockchainService -->|"RPC/Web3j"| Geth
    Monolith -->|"JDBC/SQL"| Postgres
    Monolith -->|"HTTP"| ES_Mono

    ConfigServer -->|config| Satellites
    ConfigServer -->|config| UserService
    ConfigServer -->|config| BlockchainService
    Discovery -->|discovery| Satellites
    Discovery -->|discovery| UserService
    Discovery -->|discovery| BlockchainService

    Geth <-->|load balancer| Geth
    Geth -->|"mining scripts"| Geth

    Geth -->|"events"| WSGateway
    WSGateway -->|"push"| React

    %% Observability
    Satellites -->|"metrics scrape"| PromGrafana
    UserService -->|"metrics scrape"| PromGrafana
    BlockchainService -->|"metrics scrape"| PromGrafana
    Monolith -->|"metrics scrape"| PromGrafana

    Satellites -->|"logs"| ELK
    UserService -->|"logs"| ELK
    BlockchainService -->|"logs"| ELK
    Monolith -->|"logs"| ELK

    Jenkins -->|"build images"| DockerReg
    DockerReg -->|"deploy"| Kubernetes
    Kubernetes -->|hosts| apiGateway
    Kubernetes -->|hosts| Discovery
    Kubernetes -->|hosts| ConfigServer
    Kubernetes -->|hosts| Satellites
    Kubernetes -->|hosts| UserService
    Kubernetes -->|hosts| BlockchainService
    Kubernetes -->|hosts| Monolith
    Kubernetes -->|hosts| WSGateway

    %% Click Events
    click React "https://github.com/m-elhamlaoui/keplereum/tree/main/FrontEnd/"
    click apiGateway "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend_microservice/apiGateway/"
    click ConfigServer "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend_microservice/ConfigServer/"
    click Discovery "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend_microservice/DiscoveryServer/"
    click Satellites "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend_microservice/Satellites_Service/"
    click UserService "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend_microservice/User_GroundStation_Service/"
    click BlockchainService "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend_microservice/Blockchain_Service/"
    click Monolith "https://github.com/m-elhamlaoui/keplereum/tree/main/Backend/"
    click Geth "https://github.com/m-elhamlaoui/keplereum/tree/main/Blockchain/geth-nodes/"
    click SmartContracts "https://github.com/m-elhamlaoui/keplereum/tree/main/Blockchain/build/"
    click WSGateway "https://github.com/m-elhamlaoui/keplereum/tree/main/Blockchain_WebSocket_Gateway/"

    %% Styles
    classDef frontend fill:#85C1E9,stroke:#1B4F72,color:#fff
    classDef edge fill:#AED6F1,stroke:#1B4F72,color:#000
    classDef service fill:#A9DFBF,stroke:#196F3D,color:#000
    classDef monolith fill:#F9E79F,stroke:#7D6608,color:#000
    classDef infra fill:#D7BDE2,stroke:#512E5F,color:#000
    classDef database fill:#F5CBA7,stroke:#7E5109,color:#000
    classDef monitor fill:#F1948A,stroke:#78281F,color:#000
```
