# 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](/next/admin/runtime-roles.md#reception-during-a-restart).

[Browser extension architecture](/next/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](/next/contributor/local-development.md)               |
| Choose and run the right test tier | [Testing](/next/contributor/testing.md)                                   |
| Understand a cross-module change   | [System design](/next/contributor/system-design.md)                       |
| Change persisted data safely       | [Database migration](/next/contributor/database-migration.md)             |
| Change practice review or feedback | [Practice review pipeline](/next/contributor/practice-review-pipeline.md) |
| Prepare a release                  | [Release management](/next/contributor/release-management.md)             |
| Work with a coding agent           | [Coding agents](/next/contributor/ai-agent-workflow.md)                   |

Repository-level `AGENTS.md` files hold the commands and constraints for an automated coding agent. [Coding agents](/next/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 changes the applicable ADR. The same applies to `docs/auth-architecture.md` and `docs/auth-glossary.md`.

[How we write ADRs](https://github.com/hephaestus-build/Hephaestus/blob/main/docs/decisions/README.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](/next/contributor/local-development.md) to set up your environment.

## Practice model

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