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 — the server role
│ └── 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 the server — Server runtime.
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 changes the applicable ADR.
The same applies to docs/auth-architecture.md and docs/auth-glossary.md.
How we write ADRs owns the rules: the shape, the status values, and when to correct, update or supersede an ADR.
Link an ADR 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').
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.