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

Goal	Start here
Run the repository locally	Local development
Choose and run the right test tier	Testing
Understand a cross-module change	System design
Change persisted data safely	Database migration
Change practice review or feedback	Practice review pipeline
Prepare a release	Release management
Work with a coding agent	Coding agents

Repository-level AGENTS.md files hold the commands and traps an automated coding agent must follow, and Coding agents explains how they reach it. The pages here explain the system and human workflow; when they disagree with executable configuration, generated API output, or tests, fix the prose in the same pull request.

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.

Continue with Local development to set up your environment.