Skip to main content

Contributor guide

Hephaestus is maintained by the Applied Education Technologies (AET) team at TUM. It gives developers practice feedback on pull requests, merge requests, and issues, and includes Heph, a conversational AI mentor. This guide covers the codebase and development workflow, from local setup 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.

Where the architecture decisions live​

The ADRs are not on this site, on purpose. They live in the repository under docs/decisions/, indexed by decisions/README.md — they are written against internal class names and are amended by the same PR that changes the code, so their reader already has the repository open. The same applies to docs/runbooks/, docs/auth-architecture.md and docs/auth-glossary.md.

Two rules when you touch them:

  • Link them by absolute GitHub URL from any page on this site. A relative ../decisions/… link resolves to nothing here and fails the docs build (onBrokenMarkdownLinks: 'throw').
  • An ADR records a decision, not a fix log. A bug you fixed afterwards goes in a changeset; amend an ADR only when the decision or one of its consequences actually changed.

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.