Skip to main content

Contributor Guide

Hephaestus is maintained by the Applied Education Technologies (AET) team at TUM. It delivers process-aware mentoring for agile software teams, blending repo-grounded AI guidance with real-time review analytics. This guide captures the operational knowledge you need to contribute confidently – from local development to production releases.

Repository layout​

Hephaestus/
├── webapp/                    # React + Vite front-end (public UI)
├── server/                    # Spring Boot server (GitHub + mentor APIs, webhook receiver,
│                              #   Pi mentor agent, sync NATS consumer — three runtime roles)
├── docs/                      # Docusaurus site (this documentation)
└── scripts/                   # Tooling (ERD generation, migrations, utilities)

The webhook receiver moved into server/src/main/java/.../integration/core/webhook/ and is deployed as a separate webhook-server container (same image as application-server, activated with SPRING_PROFILES_ACTIVE=prod,webhook) so an app-server restart does not drop incoming webhooks. See ADR 0008.

How to use this guide​

  • Start with Local development to prepare your workstation and understand the tooling expectations per service.
  • Review Release management and Testing before opening a PR – automation enforces the conventions documented there.
  • Dive into System design and Database when implementing larger features or debugging cross-service flows.
  • Follow the Coding & design guidelines to keep the codebase consistent across services.

Shared principles​

  1. Security first - OAuth scopes are scoped to least privilege; secrets are injected via managed infrastructure.
  2. Observability by default - We ship structured logs and OpenTelemetry traces in every service.
  3. Accessible experiences - The React webapp targets WCAG 2.1 AA; accessibility regressions must be addressed before release.
  4. Research friendly - Experiments and short-lived features sit behind feature flags and are documented for replication.

Continue with Local development to set up your environment.