# ltplus-ag/nhmzh-plugin-lca architecture

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

- Interactive diagram: https://gitdiagram.com/ltplus-ag/nhmzh-plugin-lca
- Repository: https://github.com/ltplus-ag/nhmzh-plugin-lca

## Overview

##### Project type and purpose
- Full-stack “plugin” application for Life Cycle Assessment (LCA) in the NHMzh ecosystem
- Provides a React-based UI for users to manage materials and run LCA calculations
- Hosts a small socket-based backend service that consumes and publishes Kafka messages and integrates with the KBOB material database

##### File structure
- Top-level files:
– Dockerfile.frontend, nginx.conf, index.html → static build & serving of the React app
– package.json, vite.config.ts, tsconfig.json → Vite-based frontend
– .github/workflows/docker-publish.yml → CI/CD pipeline to build & publish Docker images
- socket-backend folder:
– server.ts → entry point for the Node.js/Kafka/WebSocket backend
– KafkaService.ts, LcaCalculationService.ts → core services for message streaming & LCA logic
– config.ts → Kafka topics & connection settings
– dbSeeder.ts → script to seed initial data into a database (e.g., MongoDB)
- src folder (frontend):
– components/LCACalculator, services/, utils/, types/ → modular React app following feature & utility folders
– src/main.tsx → ReactDOM bootstrap
– socket-based or REST service connectors in services/ for Kafka & WebSocket

##### Key insights from README
- React 18, TypeScript, Tailwind CSS, Vite, Radix UI
- Consumes “qto-elements” Kafka topic, publishes “lca-data” topic
- Integrates with external KBOB Material Database API (lcadata.ch)
- Integrates upstream (QTO Plugin) and downstream (Cost Plugin, Central DB) in NHMzh

##### Main components
a. Frontend (React + Vite + Tailwind)
– Builds & serves UI via Nginx or Vite dev server
– Hosts LCACalculator component tree
– Communicates over WebSocket (or HTTP) to backend
b. Backend (Node.js + TypeScript)
– WebSocket server (server.ts) for real‐time updates
– Kafka consumer (“qto-elements”) and producer (“lca-data”)
– LcaCalculationService for core logic
– Optional DB seeder (dbSeeder.ts) writing to MongoDB
c. Kafka Cluster
– “qto-elements” topic (input)
– “lca-data” topic (output)
d. External services
– KBOB Material Database API (lcadata.ch)
– Central Database (MongoDB) in NHMzh ecosystem
– Other plugins (QTO, Cost) as upstream/downstream clients
e. DevOps & CI/CD
– Docker images (frontend & backend)
– GitHub Actions pipeline
– Nginx reverse proxy

##### Relationships & data flow
1) User interacts with the React App in browser
2) React → WebSocket → backend server
3) Backend consumes “qto-elements” from Kafka → LcaCalculationService
4) LcaCalculationService may call KBOB API for material coefficients
5) Results published to “lca-data” Kafka topic
6) Results optionally stored in MongoDB (dbSeeder or direct writes)
7) Other NHMzh modules subscribe to “lca-data”

##### Architectural patterns & principles
- Micro-service style: frontend & backend in separate containers
- Event-driven: Kafka pub/sub for decoupling
- Single-Page App (SPA) using feature-based component structure
- Separation of concerns: services layer → business logic → data models

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Application" 
        direction TB
        FrontendApp["React App (Vite+React+Tailwind)"]:::frontend
        Main["main.tsx"]:::file
        App["App.tsx"]:::file
        LCACalc["components/LCACalculator/"]:::file
        UI["components/ui/"]:::file
        WebsocketClient["websocketService.ts"]:::file
        KafkaServiceF["kafkaService.ts"]:::file
        Utils["utils/"]:::file
        Styles["index.css & theme.ts"]:::file
        ConfigFiles["vite.config.ts & tailwind.config.js"]:::file
        HTML["index.html"]:::file
        PostCSS["postcss.config.cjs"]:::file
        FrontendApp --> Main
        FrontendApp --> App
        FrontendApp --> LCACalc
        FrontendApp --> UI
        FrontendApp --> WebsocketClient
        FrontendApp --> KafkaServiceF
        FrontendApp --> Utils
        FrontendApp --> Styles
        FrontendApp --> ConfigFiles
        FrontendApp --> HTML
        FrontendApp --> PostCSS
    end

    %% Backend Layer
    subgraph "Backend Service" 
        direction TB
        BackendService["Node.js Socket & Kafka Service"]:::backend
        Server["server.ts"]:::file
        KafkaServiceB["KafkaService.ts"]:::file
        ConfigB["config.ts"]:::file
        LcaService["LcaCalculationService.ts"]:::file
        DbSeeder["dbSeeder.ts"]:::file
        DataJSON["data/indicatorsKBOB_v6.json"]:::file
        TypesB["types.ts"]:::file
        TSConfigB["tsconfig.json"]:::file
        PackageB["package.json"]:::file
        BackendService --> Server
        BackendService --> KafkaServiceB
        BackendService --> ConfigB
        BackendService --> LcaService
        BackendService --> DbSeeder
        BackendService --> TypesB
        BackendService --> TSConfigB
        BackendService --> PackageB
        DbSeeder --> DataJSON
    end

    %% Kafka Cluster
    subgraph "Kafka Cluster" 
        direction TB
        KafkaQ["qto-elements"]:::kafka
        KafkaL["lca-data"]:::kafka
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        KBOBAPI["KBOB Material DB API (lcadata.ch)"]:::external
        MongoDB["MongoDB (Central DB)"]:::db
        QTOPlugin["QTO Plugin"]:::external
        CostPlugin["Cost Plugin"]:::external
        Reporting["Reporting Module"]:::external
    end

    %% CI/CD & DevOps
    subgraph "CI/CD & DevOps" 
        direction TB
        Workflow[".github/workflows/docker-publish.yml"]:::ci
        DockerFrontend["Dockerfile.frontend"]:::ci
        DockerBackend["socket-backend/Dockerfile.backend"]:::ci
        Nginx["nginx.conf"]:::ci
        Workflow --> DockerFrontend
        Workflow --> DockerBackend
        DockerFrontend --> Nginx
    end

    %% User
    User["User (Browser)"]:::user

    %% Connections
    User -->|opens UI| FrontendApp
    FrontendApp -->|WebSocket| Server
    Server -->|consumes| KafkaQ
    Server -->|publishes| KafkaL
    Server -->|calls| KBOBAPI
    KafkaL -->|subscribed by| CostPlugin
    KafkaL -->|subscribed by| Reporting
    Server -->|writes| MongoDB
    DbSeeder -->|seeds| MongoDB

    %% Styles and Clicks
    classDef frontend fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef backend fill:#E8F5E9,stroke:#A5D6A7,color:#1B5E20;
    classDef kafka fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
    classDef db fill:#ECEFF1,stroke:#B0BEC5,color:#37474F;
    classDef external fill:#F3E5F5,stroke:#CE93D8,color:#4A148C;
    classDef ci fill:#E0F7FA,stroke:#4DD0E1,color:#006064;
    classDef user fill:#FFEBEE,stroke:#EF9A9A,color:#B71C1C;
    classDef file fill:#FFFFFF,stroke:#BDBDBD,color:#212121,stroke-dasharray: 2 2;

    click FrontendApp "https://github.com/ltplus-ag/nhmzh-plugin-lca/tree/main/src/"
    click Main "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/main.tsx"
    click App "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/App.tsx"
    click LCACalc "https://github.com/ltplus-ag/nhmzh-plugin-lca/tree/main/src/components/LCACalculator/"
    click UI "https://github.com/ltplus-ag/nhmzh-plugin-lca/tree/main/src/components/ui/"
    click WebsocketClient "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/services/websocketService.ts"
    click KafkaServiceF "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/services/kafkaService.ts"
    click Styles "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/index.css"
    click Styles "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/theme.ts"
    click PostCSS "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/postcss.config.cjs"
    click ConfigFiles "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/tailwind.config.js"
    click ConfigFiles "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/vite.config.ts"
    click HTML "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/index.html"
    click DockerFrontend "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/Dockerfile.frontend"

    click BackendService "https://github.com/ltplus-ag/nhmzh-plugin-lca/tree/main/socket-backend/"
    click Server "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/server.ts"
    click KafkaServiceB "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/KafkaService.ts"
    click ConfigB "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/config.ts"
    click LcaService "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/LcaCalculationService.ts"
    click DbSeeder "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/dbSeeder.ts"
    click DataJSON "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/data/indicatorsKBOB_v6.json"
    click TypesB "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/types.ts"
    click TSConfigB "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/tsconfig.json"
    click PackageB "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/package.json"
    click DockerBackend "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/socket-backend/Dockerfile.backend"

    click KBOBAPI "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/src/services/kbobService.ts"
    click Workflow "https://github.com/ltplus-ag/nhmzh-plugin-lca/blob/main/.github/workflows/docker-publish.yml"
```
