# 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](/admin/runtime-roles.md#monolith-vs-split-pod).

[Browser extension architecture](/contributor/browser-extension.md) explains the extension and its connection to the server.

## How to use this guide

| Goal                               | Start here                                                           |
| ---------------------------------- | -------------------------------------------------------------------- |
| Run the repository locally         | [Local development](/contributor/local-development.md)               |
| Choose and run the right test tier | [Testing](/contributor/testing.md)                                   |
| Understand a cross-module change   | [System design](/contributor/system-design.md)                       |
| Change persisted data safely       | [Database migration](/contributor/database-migration.md)             |
| Change practice review or feedback | [Practice review pipeline](/contributor/practice-review-pipeline.md) |
| Prepare a release                  | [Release management](/contributor/release-management.md)             |
| Work with a coding agent           | [Coding agents](/contributor/ai-agent-workflow.md)                   |

Repository-level `AGENTS.md` files hold the commands and constraints for an automated coding agent. [Coding agents](/contributor/ai-agent-workflow.md) 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/`](https://github.com/hephaestus-build/Hephaestus/tree/main/docs/decisions). [`decisions/README.md`](https://github.com/hephaestus-build/Hephaestus/blob/main/docs/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](/contributor/local-development.md) to set up your environment.

## Practice model

The [data model](/contributor/practice-feedback-schema.md) owns durable review and feedback relationships. The [pipeline](/contributor/practice-review-pipeline.md) owns evidence and delivery boundaries. The [review glossary](/contributor/practice-review-glossary.md) owns operation terms and scientific correspondence.