vergabe-teilnahme/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Vergabe Teilnahme** is a web-based tender/bid management system (internal collaboration tool) that supports a company through the full lifecycle of public and private procurement bids — from initial research through post-award retrospective. The language of the application and all domain documentation is **German**.

The authoritative requirements are in `wiki/ProductRequirementsDocument.md`. Technical architecture in `wiki/ArchitectureBlueprint.md`. Use cases in `wiki/UseCaseCatalog.md`.

## Tech Stack

**Django 6.x** · **uv** (package manager) · **Tailwind CSS v4** (via Vite) · **HTMX 2.x** · **Alpine.js 3.x** · **PostgreSQL 16+** (psycopg3)

## Entwicklungs-Commands

Run `make` without arguments for a full list with descriptions.

```bash
make db           # PostgreSQL starten (Noop wenn :5432 bereits erreichbar)
make css          # Tailwind CSS Watch-Modus — Terminal A, laufen lassen
make dev          # Django-Dev-Server auf :9000 — Terminal B
make seed         # Seed-Daten laden (idempotent)
make superuser    # Superuser anlegen (einmalig für /admin/)
make migrate      # Migrations generieren und ausführen
make test         # pytest ausführen
make lint         # ruff + mypy
uv run pytest vergabe_teilnahme/apps/<app>/tests/    # Einzelne Testdatei
```

## Projektstruktur

```
vergabe_teilnahme/
├── apps/           # Alle Django-Apps
│   ├── core/       # FlexibleModel, CustomAttribute, EntityFieldConfig, Freigabe
│   ├── accounts/   # Mitarbeiter (AbstractUser)
│   └── ...         # je eine App pro Fachdomäne
├── settings/       # base.py, dev.py, prod.py
└── urls.py

static/
├── src/main.css    # Tailwind-Quelldatei (mit @layer components und @theme brand tokens)
├── vendor/         # HTMX, Alpine.js (lokal, kein CDN)
└── dist/           # Build-Output (gitignored)

workplans/          # Ralph-Loop-Workplans (WP-0001 bis WP-0012)
wiki/               # PRD, Blueprint, Use-Case-Katalog
```

## Shared Infrastructure Note

Port 5432 is used by `infra-postgres-1` (the Custodian shared PostgreSQL container). The `vergabe_db` database and `vergabe` user are created there. `docker-compose.dev.yml` documents the intended standalone setup but is not started when infra container is active.

## Domain Model — Key Concepts

The system manages **Ausschreibungen** (tenders) through 8 phases:

| Phase | Name |
|-------|------|
| 1 | Recherche & Unterlagen bereitstellen |
| 2 | Teilnahmeentscheidung treffen |
| 3 | Detaillierte Durchsicht & offene Punkte |
| 4 | Bieterfragen, Subunternehmer, offene Punkte klären |
| 5 | Preismodell dokumentieren |
| 6 | Unterlagen finalisieren |
| 7 | Abgabe |
| 8 | Zuschlag / Nachbetrachtung |

Core entities: `Ausschreibung`, `Los` (lot), `Anforderung` (requirement), `Aufgabe` (task), `Bieterfrage` (bidder question), `Dokument`, `Subunternehmer`, `Preispunkt` (price point), `Marktbegleiter` (competitor), `Nachweis` (compliance certificate), `Referenz`, `Freigabe` (approval), `Nachbetrachtung` (retrospective).

**Vergleichsgewicht** (comparison weight): price points carry a weight in [0.0, 2.0] (default 1.0). Weighted averages use `Σ(value × weight) / Σ(weight)`; points with weight 0.0 are excluded from averages entirely.

## Custodian State Hub

This repo is tracked by the Custodian State Hub. At session start inside this repo, call `get_domain_summary("<domain_slug>")` via the `state-hub` MCP tool. End every non-trivial session with `add_progress_event()`.