# hopps-app/hopps architecture

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

- Interactive diagram: https://gitdiagram.com/hopps-app/hopps
- Repository: https://github.com/hopps-app/hopps

## Overview

##### Main System Components
The system consists of several microservices and components that should be represented as distinct blocks:

a. Frontend Layer:
- SPA (Single Page Application) built with React/TypeScript
- Mobile Application
- Keycloak Theme for authentication UI

b. Backend Services:
- Organization Service (app.hopps.org)
- Financial Service (app.hopps.fin)
- Document AI Service (app.hopps.az-document-ai)
- ZugFerd Service (app.hopps.zugferd)

c. Infrastructure Components:
- Keycloak for authentication
- PostgreSQL databases
- Kafka for event streaming
- MinIO for object storage
- Azure AI services integration

##### Component Relationships and Data Flow

- User interactions flow from Frontend → Backend Services
- Authentication flow through Keycloak
- Event-driven communication between services via Kafka
- Document processing flow:
Frontend → Financial Service → Document AI Service → Azure AI
- Data persistence flows to PostgreSQL databases
- File storage flows to MinIO

##### Key Architectural Patterns to Highlight

a. Microservices Architecture:
- Clear service boundaries
- Independent deployability
- Inter-service communication

b. Event-Driven Architecture:
- Kafka message flows between services
- Event processing patterns

c. Security Layer:
- Keycloak integration
- Service-to-service authentication

##### Deployment Architecture

Kubernetes deployment aspects:
- Container orchestration
- Helm charts structure
- Service discovery and routing

##### Additional Details

- API gateways
- Load balancers
- Monitoring components
- Scaling capabilities
- Environment-specific configurations

Remember to emphasize:
- The AI document processing pipeline
- The event-driven nature of the system
- The security architecture
- The scalability aspects

This will provide a clear understanding of how the system components interact while processing accounting documents and managing organizational data.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef infrastructure fill:#f1c40f,stroke:#f39c12,color:black
    classDef security fill:#e74c3c,stroke:#c0392b,color:white
    classDef database fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef ai fill:#9b59b6,stroke:#8e44ad,color:white

    %% Frontend Layer
    subgraph Frontend
        SPA[React SPA]:::frontend
        Mobile[Mobile App]:::frontend
        KTheme[Keycloak Theme]:::frontend
    end

    %% Security Layer
    subgraph Security
        KC[Keycloak]:::security
        LB[Load Balancer]:::security
    end

    %% Backend Services
    subgraph Services
        OS[Organization Service]:::backend
        FS[Financial Service]:::backend
        DAIS[Document AI Service]:::backend
        ZS[ZugFerd Service]:::backend
    end

    %% Infrastructure
    subgraph Infrastructure
        KF[Kafka]:::infrastructure
        MINIO[(MinIO)]:::database
        DB[(PostgreSQL)]:::database
    end

    %% AI Services
    subgraph AI
        AZ[Azure AI]:::ai
    end

    %% Connections
    SPA --> LB
    Mobile --> LB
    KTheme --> KC
    LB --> KC
    KC --> Services
    
    OS --> DB
    FS --> DB
    DAIS --> DB
    ZS --> DB
    
    FS --> KF
    DAIS --> KF
    
    FS --> MINIO
    DAIS --> MINIO
    
    DAIS --> AZ

    %% Click Events
    click SPA "https://github.com/hopps-app/hopps/tree/main/frontend/spa"
    click Mobile "https://github.com/hopps-app/hopps/tree/main/mobile"
    click KTheme "https://github.com/hopps-app/hopps/tree/main/frontend/keycloak-theme"
    click OS "https://github.com/hopps-app/hopps/blob/main/backend/app.hopps.org"
    click FS "https://github.com/hopps-app/hopps/blob/main/backend/app.hopps.fin"
    click DAIS "https://github.com/hopps-app/hopps/blob/main/backend/app.hopps.az-document-ai"
    click ZS "https://github.com/hopps-app/hopps/blob/main/backend/app.hopps.zugferd"
    click MINIO "https://github.com/hopps-app/hopps/blob/main/infrastructure/minio/docker-compose.yaml"
    click DB "https://github.com/hopps-app/hopps/blob/main/infrastructure/hopps-app/postgres_init.sql"
    click KC "https://github.com/hopps-app/hopps/blob/main/infrastructure/hopps-app/keycloak_default_realm.json"
    click AZ "https://github.com/hopps-app/hopps/blob/main/backend/app.hopps.az-document-ai/src/main/java/app/hopps/AzureAiService.java"
    click KF "https://github.com/hopps-app/hopps/blob/main/backend/app.hopps.fin/src/main/java/app/hopps/fin/kafka/DocumentProducer.java"

    %% Legend
    subgraph Legend
        F[Frontend]:::frontend
        B[Backend]:::backend
        I[Infrastructure]:::infrastructure
        S[Security]:::security
        D[(Database)]:::database
        AI[AI Services]:::ai
    end
```
