# ls1intum/hephaestus architecture

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

- Interactive diagram: https://gitdiagram.com/ls1intum/hephaestus
- Repository: https://github.com/ls1intum/hephaestus

## Overview

##### Main Components Identification

The system consists of three main server components and a web application:
- Application Server (Java/Spring Boot)
- Intelligence Service (Python)
- Webhook Ingest Service (Python)
- Web Application (Angular)

##### Key Architectural Elements

a. Frontend Layer:
- Angular-based web application with extensive UI components
- Keycloak authentication integration
- Component-based architecture with modular UI libraries

b. Backend Services:
- Application Server:
- REST API endpoints
- Git provider integration
- Leaderboard and gamification features
- User management and workspace handling

- Intelligence Service:
- AI/ML capabilities
- Mentor functionality
- API for intelligent features

- Webhook Ingest:
- NATS message broker integration
- GitHub webhook handling

##### External Services Integration
- Keycloak for authentication
- GitHub integration
- Slack integration
- Sentry for monitoring

**[Web Application (Angular)]**
- User Interface
- Authentication
- State Management

**[API Gateway/Load Balancer]**
- Route traffic to appropriate services
- Handle SSL termination

**[Application Server]     [Intelligence Service]     [Webhook Ingest]**
- User Management        - AI/ML Processing         - Webhook Handling
- Workspace Management   - Mentoring Logic          - Event Processing
- Leaderboard           - Analysis Features         - NATS Integration

**[Database]              [Message Broker]           [Cache]**
- PostgreSQL            - NATS                     - Redis

**[External Services]**
- Keycloak
- GitHub
- Slack
- Sentry

##### Additional Elements

Following annotations:
- Security boundaries
- Load balancing points
- Caching layers
- Event flows
- Authentication flows

##### Deployment Context

A small deployment context section showing:
- Container orchestration
- Service scaling
- High availability setup

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph Client
        WA[Web Application]:::frontend
        UI[UI Components]:::frontend
    end

    %% API Gateway Layer
    LB[API Gateway/Load Balancer]:::infrastructure

    %% Service Layer
    subgraph Services
        AS[Application Server]:::backend
        IS[Intelligence Service]:::backend
        WI[Webhook Ingest]:::backend
    end

    %% Data Layer
    subgraph Data
        DB[(PostgreSQL)]:::database
        NATS[NATS Message Broker]:::messaging
        REDIS[(Redis Cache)]:::cache
    end

    %% External Services
    subgraph External
        KC[Keycloak]:::external
        GH[GitHub]:::external
        SLACK[Slack]:::external
        SENTRY[Sentry]:::external
    end

    %% Core Components
    subgraph Core_Components
        UM[User Management]:::component
        WM[Workspace Management]:::component
        LB_COMP[Leaderboard]:::component
        MENTOR[Mentor System]:::component
    end

    %% Relationships
    WA --> LB
    UI --> WA
    LB --> AS
    LB --> IS
    LB --> WI
    AS --> DB
    IS --> DB
    WI --> NATS
    AS --> NATS
    AS --> REDIS
    AS --> KC
    AS --> GH
    AS --> SLACK
    AS --> SENTRY
    WI --> GH
    AS --> UM
    AS --> WM
    AS --> LB_COMP
    AS --> MENTOR
    IS --> MENTOR

    %% Click Events
    click WA "https://github.com/ls1intum/Hephaestus/tree/develop/webapp/"
    click UI "https://github.com/ls1intum/Hephaestus/tree/develop/webapp/src/libs/ui/"
    click AS "https://github.com/ls1intum/Hephaestus/tree/develop/server/application-server/"
    click IS "https://github.com/ls1intum/Hephaestus/tree/develop/server/intelligence-service/"
    click WI "https://github.com/ls1intum/Hephaestus/tree/develop/server/webhook-ingest/"
    click UM "https://github.com/ls1intum/Hephaestus/tree/develop/server/application-server/src/main/java/de/tum/in/www1/hephaestus/workspace/"
    click WM "https://github.com/ls1intum/Hephaestus/tree/develop/server/application-server/src/main/java/de/tum/in/www1/hephaestus/workspace/"
    click LB_COMP "https://github.com/ls1intum/Hephaestus/tree/develop/server/application-server/src/main/java/de/tum/in/www1/hephaestus/leaderboard/"
    click MENTOR "https://github.com/ls1intum/Hephaestus/tree/develop/server/application-server/src/main/java/de/tum/in/www1/hephaestus/mentor/"

    %% Styles
    classDef frontend fill:#2196F3,stroke:#1565C0,color:white
    classDef backend fill:#4CAF50,stroke:#2E7D32,color:white
    classDef database fill:#FF9800,stroke:#EF6C00,color:white
    classDef messaging fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef cache fill:#FF5722,stroke:#D84315,color:white
    classDef external fill:#607D8B,stroke:#37474F,color:white
    classDef infrastructure fill:#795548,stroke:#4E342E,color:white
    classDef component fill:#3F51B5,stroke:#283593,color:white
```
