# eclipse-tractusx/portal-frontend architecture

> Architecture diagram of the GitHub repository eclipse-tractusx/portal-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eclipse-tractusx/portal-frontend
- Repository: https://github.com/eclipse-tractusx/portal-frontend

## Overview

##### Project Type and Purpose
- This is a full-stack portal application’s frontend, implemented as a single-page React/TypeScript app (Vite-powered).
- It serves as the “Portal Frontend” UI that users access via browser and interacts with the portal-backend (REST API) and IAM service for authentication/authorization.

##### High-Level Architecture Components
a. Client Browser
- Runs the React SPA (bundled by Vite)
- Hosts UI components, page routes, localization, state (Redux Toolkit slices), and UI services (AccessService, RequestService, etc.)
b. Static File Server / CDN (Nginx)
- Serves built assets (index.html, JS/CSS bundles, public/ manifest.json, testdata)
- Configuration in .conf/nginx.conf and Dockerfiles
c. Portal Backend (external service)
- Exposes REST endpoints consumed via features/* apiSlice.ts files
- Provides business data (apps, users, companies, notifications, etc.)
d. IAM Service (external OAuth2/OpenID Connect)
- Handles login, token issuance, user identity management
e. Shared Components Library
- portal-shared-components (imported, overrides MUI, provides theme, global frame)
f. DevOps & CI/CD
- Build pipeline in GitHub Actions (.github/workflows/*.yml)
- Docker image build (.conf/Dockerfile.full, Dockerfile.prebuilt)
- Helm chart in portal repo for Kubernetes deployment

##### Interactions and Data Flows
- User → Browser: enters URL → index.html
- Browser → Nginx (or static host): fetches JS/CSS bundles
- On user action (page load, overlay, form submit), React “features” modules dispatch RTK queries to portal-backend endpoints
- Backend returns JSON → RequestService normalizes → Redux store updates → UI components subscribe via hooks (useApiGet, useTranslation)
- Auth flows: on first load or protected route, the SPA redirects to IAM, obtains JWT token, stores it in LocalStorage or cookie, then includes bearer token in API requests
- Shared-components library provides layout (Header, Footer, MobileMenu), global theming, and basic building blocks (Buttons, Inputs)

##### Architectural Patterns and Design Principles
- Single-Page Application (SPA) with client-side routing (react-router)
- Feature-driven file structure: each domain area (apps, admin, serviceMarketplace, etc.) lives in src/features, with RTK apiSlice + slice + types
- Component hierarchy: top-level layout (Main.tsx → AuthorizingRouter) → pages → overlays → shared/basic/shared/frame templates
- State management: Redux Toolkit (RTK Query for API calls, createSlice for local state)
- Testing: Jest config, Cypress end-to-end tests

##### Diagramming Recommendations
- Browser (SPA)
- API Layer
- Backend Services
- Authentication Service
- Static File Server
- CI/CD Pipeline
- Browser → Nginx (GET assets)
- SPA → IAM (OAuth redirect + token)
- SPA → Portal-Backend (REST calls)
- CI/CD → Docker Registry → Kubernetes
- Blue for client/UI
- Green for data/state
- Orange for external services
- Grey for infrastructure/CI

##### Essential Elements
- Labels: HTTPs endpoints, JWT token flow, Redux store, SCSS theming

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer (Client/UI)
    subgraph "Presentation Layer (React SPA)" 
        direction TB
        B1["React SPA Entry Point"]:::frontend
        B2["Main Layout (Main.tsx)"]:::frontend
        B3["Auth Router (AuthorizingRouter.tsx)"]:::frontend
        B4["UI Components Library"]:::frontend
        B5["Page Components"]:::frontend
        B6["Modals/Overlays"]:::frontend
        B7["Localization Assets"]:::frontend
        B8["Global Styles & Theming"]:::frontend
        B9["Public HTML Template"]:::frontend
    end

    %% Data Layer
    subgraph "Data Layer (Redux & RTK Query)"
        direction TB
        D1["Redux Store Configuration"]:::data
        D2["Feature RTK Slices"]:::data
    end

    %% Integration Layer
    subgraph "Integration Layer (UI Services)"
        direction TB
        I1["Services (Access, Request, Common, User, ...)"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        E1["Portal Backend (REST API)"]:::external
        E2["IAM Service (OAuth2/OpenID)"]:::external
        E3["Shared Components Library"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        direction TB
        InfraCI["CI/CD Pipeline"]:::infra
        InfraDocker["Docker Image Builds"]:::infra
        InfraNG["Nginx Static File Server"]:::infra
        InfraHelm["Helm Charts & Kubernetes"]:::infra
    end

    %% Connections
    B1 -->|HTTPS GET assets| InfraNG
    B1 -->|OAuth2 Redirect / Bearer Token| E2
    B1 -->|REST/JSON API Calls| E1
    B1 -->|Uses Library| E3
    B1 -->|Dispatches Queries| D2
    B2 -->|Renders Layout| B1
    B3 -->|Handles Routing| B1
    B4 -->|Imported Components| B1
    B5 -->|Page Rendering| B1
    B6 -->|Loads Translations| B1
    B7 -->|Applies Styles| B1
    B9 -->|Serves index.html| InfraNG

    B1 -->|Invokes Services| I1
    I1 -->|API Requests| E1
    D2 -->|Calls Endpoints| E1
    D1 -->|Stores State| B1
    D2 -->|Updates Store| D1

    InfraCI -->|Build & Test| InfraDocker
    InfraDocker -->|Produces Image| InfraNG
    InfraCI -->|Deploy Charts| InfraHelm
    InfraHelm -->|Runs on| InfraNG

    %% Click Events
    click B1 "https://github.com/eclipse-tractusx/portal-frontend/blob/main/src/index.tsx"
    click B2 "https://github.com/eclipse-tractusx/portal-frontend/blob/main/src/components/Main.tsx"
    click B3 "https://github.com/eclipse-tractusx/portal-frontend/blob/main/src/components/AuthorizingRouter.tsx"
    click B4 "https://github.com/eclipse-tractusx/portal-frontend/tree/main/src/components/shared"
    click B5 "https://github.com/eclipse-tractusx/portal-frontend/tree/main/src/components/pages"
    click B6 "https://github.com/eclipse-tractusx/portal-frontend/tree/main/src/assets/locales"
    click B7 "https://github.com/eclipse-tractusx/portal-frontend/tree/main/src/components/styles"
    click B9 "https://github.com/eclipse-tractusx/portal-frontend/blob/main/index.html"
    click D1 "https://github.com/eclipse-tractusx/portal-frontend/blob/main/src/features/store.ts"
    click D2 "https://github.com/eclipse-tractusx/portal-frontend/tree/main/src/features"
    click I1 "https://github.com/eclipse-tractusx/portal-frontend/tree/main/src/services"
    click InfraNG "https://github.com/eclipse-tractusx/portal-frontend/blob/main/.conf/nginx.conf"
    click InfraDocker "https://github.com/eclipse-tractusx/portal-frontend/blob/main/.conf/Dockerfile.full"
    click InfraCI "https://github.com/eclipse-tractusx/portal-frontend/tree/main/.github/workflows"
    
    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef data fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef external fill:#FFF5B1,stroke:#B08800,color:#B08800;
    classDef infra fill:#EDEDED,stroke:#6A737D,color:#6A737D;
```
