Contributor guide

The Applied Education Technologies (AET) team at TUM maintains Hephaestus. Hephaestus reviews the pull requests, issues, and code reviews your team already writes against the engineering practices you choose. It gives each developer feedback that cites their work and names a next step. It includes Hephaestus, a conversational assistant. This guide covers the codebase and development workflow, from local setup to production releases.

Repository layout

Hephaestus/
├── webapp/                    # React + Vite front-end (public UI)
├── extension/                 # Browser extension
├── server/                    # Gradle multi-project build
│   ├── application/           # Spring Boot application — server, worker, and webhook roles
│   └── generated-clients/     # Generated GitHub, GitLab, and Outline transports
├── docs/                      # Docusaurus site (this documentation)
└── scripts/                   # Tooling (ERD generation, migrations, utilities)

The webhook receiver lives under integration/core/webhook/ in the application module and runs in its own container in production — Runtime roles.

Browser extension architecture explains the extension and its connection to the server.

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 constraints for an automated coding agent. Coding agents explains how the agent receives them. The pages here explain the system and human workflow. If 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 intentionally not on this site. They live in the repository under docs/decisions/. decisions/README.md indexes them. They refer to internal class names, so their reader already has the repository open. The PR that changes the code also amends the applicable ADR. The same applies to 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. Record a later bug fix in a changeset. Amend an ADR only when the decision or one of its consequences changed.

Continue with Local development to set up your environment.

Practice model

The data model owns durable review and feedback relationships. The pipeline owns evidence and delivery boundaries. The review glossary owns operation terms and scientific correspondence.