System Design

Overview

Hephaestus is designed using an architecture-first approach. To develop and visualize our system design, we use StarUML, a professional UML modeling software that allows for comprehensive representation of system components, relationships, and behaviors. The source file for all models and diagrams displayed in this documentation can be found on Github and here.

Top-Level Design

The top-level architecture diagram illustrates Hephaestus as a layered system with clear boundaries between components. The diagram shows the system divided into Hephaestus-internal and external components.

Internally, Hephaestus is based on a client-server architecture with multiple server components. We differentiate between the Application Server and the Intelligence Service as well as the smaller Webhook Ingest and the User Management System.

Externally, Hephaestus is connected to the Code Review System, the Notification System, and the Analytics Platform. The Code Review System is an abstraction for the actual Git hosting platform, e.g. GitHub or GitLab. The Webhook Ingest provides an endpoint this platform can send webhooks to. The Application Server on the other hand utilizes the platform’s API to supplement the webhook data with additional information or fill in missing data. The User Management System utilizes the Code Review System as identity provider to create a direct dependency for the user login. The Notification System bridges the gap between the client and server to send notifications to users. The Analytics Platform is used to store and analyze data, generally limited to anonymous usage metrics of the web application.

Hephaestus Top Level Architecture (UML Component Diagram)

Gamification Model

To implement gamification features, we built upon an adapted basic structure by the Github’s webhooks. The analysis object model presents the data structure of Hephaestus through class relationships. Note that the model is simplified and some relationships are not shown for brevity.

+Github’s webhook structure is more or less directly mapped to the Review, PullRequest and Developer classes. The original events contain lots of irrelevant and duplicate information, which is why we added certain relationships to the classes to reduce redundancy.

Around these core classes, we added additional classes to model the gamification features. Most importantly, we introduced the Leaderboard and Reward abstractions to model the leaderboard and rewards system, respectively. All gamification related data is managed by the GamificationDashboard.

Gamification Analysis Object Model (UML Class Diagram)

AI Mentor

To implement AI mentor features for self-reflective practices we utilize LangGraph, a library built by LangChain that allows users to create complex, stateful, multi-agent applications using graph-based architectures.

The system maintains a state, which represents a current snapshot of the application. Each call to the AI Mentor triggers a run of the graph, which consists of nodes and edges. Nodes receive the current state as input, perform specific operations — such as updating state parameters or generating responses — and return an updated state. Edges determine the next node to execute based on the current state, functioning as either conditional branches or fixed transitions.

There are four main elements of the graph:

Storage update nodes: Functions that update data saved in storage, maintaining long-term memory across all interactions with the AI Mentor.
Response generation nodes: Functions responsible for generating responses that users receive in the chat interface.
State update nodes: Functions that update the current state of the graph (a TypedDict containing information about the current chat).
Conditions, or conditional edges: Edges that evaluate the current state and determine which node to execute next.

LangGraph Graph Structure Used for Each of the Response Generation Calls

User Interaction

As web applications are highly interactive, we want to model the basic interactions between the user and the system, giving a high-level overview of the possible user journeys. For that reason, we focus on a Developer as the primary actor of the system and model their interactions with the system.

Hephaestus Gamification Use Case Diagram — Hephaestus Gamification Use Cases (UML Use Case Diagram)

Hephaestus AI Mentor Use Case Diagram — Hephaestus AI Mentor Use Cases (UML Use Case Diagram)

Core Workflows

The following sections describe the core workflows of Hephaestus in more detail.

Login and Authorization

The login and authorization workflow is the first step in the user journey. It is used to authenticate the user and authorize the application to access their resources. Primarily, the user can log in via the Code Review System (e.g. GitHub or GitLab).

Hephaestus Github Login Authorization Flow (UML Sequence Diagram)

New Review Activity

The new review activity is the fundamental workflow allowing Hephaestus to provide real-time data to the user. It is triggered when a new review is created and updates the leaderboard (and in the future the user’s rewards) based on the new activity. This flow heavily relies on the Webhook Ingest to receive the webhook events from the Code Review System and the Application Server to process them accordingly.