vergabe-teilnahme/SCOPE.md

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Web application that structures a company's participation in tenders
(Ausschreibungen) end-to-end, from research through submission to
post-award retrospective.

---

## Core Idea

**Vergabe Teilnahme** ("tender participation") guides a team through the
full lifecycle of bidding on a public or private tender: collecting tender
documents, analyzing requirements, deciding whether to participate, tracking
open items, finalizing pricing and documents, submitting on time, and
capturing reusable knowledge afterwards — win or lose. It is phase-guided,
never phase-locked: every element of a tender is reachable at any time, and
there is no forced completeness outside real submission-deadline
constraints. All data entry is manual in this first build stage — no
automated ingestion from tender platforms.

It operates on three levels, per `wiki/ProductRequirementsDocument.md`:

| Level | Content |
|---|---|
| Operational | deadlines, documents, tasks, lots (Lose), requirements, bidder questions, submission |
| Management | participate/no-bid decision, approvals, pricing level, subcontractor selection, outcome, retrospective |
| Strategic | reusable evidence/references, market price observation, loss reasons, win factors, competitor (Marktbegleiter) analysis |

---

## Product direction — 2026-09-08

Primary customer service/UI repository for the HelixForge factory, selected by
the user. Initial delivery preserves a single-company boundary; customer release
requires explicit deployment, access, persistence, restore and support acceptance
in VERGABE-WP-0019 (invited pilot) and VERGABE-WP-0018 (factory delivery). The original internal collaboration workflows remain valid.

## In Scope

- Tender (Ausschreibung) and lot (Los) tracking through 8 navigable phases
- Requirements analysis and bidder-question (Bieterfragen) handling
- Task management (Aufgaben) scoped to a tender or a lot
- Document management (Dokumente) for tender materials and submission artifacts
- Pricing (Preise) tracking per lot/tender
- Submission and post-award retrospective (Abgabe/Nachbetrachtung)
- Partner and reference library (Partner/Bibliothek) for reusable evidence
- Competitor/market observation (Marktbegleiter)
- Feedback/bug capture within the app (Feedback)
- Issue-tracking integration via `issue-core` (task facade, not a UI replacement)

## Out of Scope

- External user accounts for partners/subcontractors/service providers (data
  objects only in this build stage, no system access of their own)
- Shared-application multi-tenancy; invited companies use isolated deployments
- Automated ingestion from tender platforms, SharePoint, Teams, CRM, ERP,
  email, or calendars (deliberately manual-entry-first for v1)
- Certification or legal validity of submissions — the system tracks
  process state, it is not a legal compliance authority

---

## Relevant When

- Deciding whether to bid on a tender and needing structured deadline,
  document, and requirement tracking across a team
- Needing a system of record for pricing decisions, submission evidence,
  and post-award retrospectives on public/private tenders
- Wanting to reuse prior tender evidence, references, or competitor/pricing
  observations when evaluating a new tender

## Not Relevant When

- Needing external bidder/partner portal access (not built yet)
- Needing automated tender discovery or platform integration (out of scope
  for this build stage)
- Needing generic project management unrelated to the tender-participation
  domain

---

## Current State

- Status: active
- Implementation: substantial — 12 Django apps covering the full phase
  model (accounts, aufgaben, ausschreibungen, bibliothek, core, dokumente,
  feedback, lose, marktbegleiter, nachbetrachtung, partner, preise); 17
  workplans (WP-0001–WP-0017) implemented in sequence from project
  scaffold through whynot-design token adoption
- Stability: evolving — manual-entry-first v1; Forgejo gates images with application/container acceptance
  (`.gitea/`/`.forgejo/` absent)
- Usage: internal collaboration tool, not yet published for external use

---

## How It Fits

- Upstream dependencies: `issue-core` (task-tracking facade, see
  `vergabe_teilnahme/apps/aufgaben/issue_facade.py`), `whynot-design`
  (visual language, vendored CSS/tokens)
- Downstream consumers: none known
- Often used with: `railiance-apps` (deployment target per its own SCOPE.md,
  which names `vergabe-teilnahme` as a user-facing service it deploys)

---

## Terminology

- Preferred terms: Ausschreibung (tender), Los (lot), Aufgabe (task),
  Marktbegleiter (competitor/market companion), Nachbetrachtung (post-award
  retrospective)
- Also known as: "Vergabe Teilnahme" (product name), "tender participation
  management system" (English gloss)
- Potentially confusing terms: "Partner" here means reference/subcontractor
  data objects, not system users

---

## Related / Overlapping Repositories

- `issue-core` — task-tracking backend consumed via `issue_facade.py`
- `whynot-design` — visual language vendored into `static/src/vendor/`
- `railiance-apps` — deployment/workload layer for this service

---

## Getting Oriented

- Start with: `wiki/ProductRequirementsDocument.md` (product intent, in
  German), `wiki/ArchitectureBlueprint.md` (technology stack and design
  principles)
- Key files / directories: `vergabe_teilnahme/apps/` (12 domain apps),
  `vergabe_teilnahme/urls.py` (route map), `workplans/` (WP-0001–0017
  build history)
- Entry points: `manage.py runserver`; `vergabe_teilnahme/urls.py` maps
  `/ausschreibungen/`, `/lose/`, `/aufgaben/`, `/dokumente/`, and more

---

## Provided Capabilities

Registered in `registry/capabilities/capability.procurement.vergabe-teilnahme.md`
(reuse-surface federation; vector **D3/A1/C1/R1** after SCOPE.md fill-in and
REUSE-WP-0017-T05 entry-2 review, 2026-07-07).

---

## Notes

Product and architecture documentation (`wiki/`) is in German; this SCOPE.md
is in English per the reuse-surface registry's Markdown-first, agent-facing
convention. Refer to `wiki/ProductRequirementsDocument.md` for the
authoritative German-language product definition.


## Invited-pilot milestone — 2026-09-11

One company, several manually onboarded users; pricing follows later by user
decision. Django login and protected downloads are source-tested. Native release,
data recovery, user acceptance and support remain in VERGABE-WP-0019 and
RAPPS-WP-0014. Automated source/container acceptance already exists in Forgejo;
older current-state statements about missing CI are historical.


## Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through
`.generated-work-records.json` and the isolated `.generated-work-records.mk`
recipe. `make generated-work-records` reuses the State Hub renderer through
the Custodian adapter; `make generated-work-records-check` verifies byte-exact
agreement with staged Markdown. The pre-commit hook uses the isolated recipe,
preserves unstaged index edits by refusing them, and retains the generated-only
commit guard and existing security checks. It does not contact the hub, alter
workplan statuses or grant deployment authority. This consumes shared tooling;
it does not make this repository the provider of the generator capability.

## Local orientation brief policy — 2026-10-19

`.custodian-brief.md` is a local, ignored State Hub orientation snapshot. Its
existing bytes remain available for offline session startup; refreshing it does
not require a Git commit. Authored workplans and the generated WORK-RECORDS index
retain their existing source and staged-generation contracts. No runtime or
credential change follows from this repository hygiene policy.


## Provisional synthetic pilot sizing

`scripts/synthetic_pilot.py` drives real loopback HTTP through an isolated Gunicorn
instance and disposable PostgreSQL16. `config/synthetic-pilot.json` tunes workload
assumptions, and `config/synthetic-sizing-margins.json` tunes the conservative local
resource-envelope calculation. Per-operation latency/errors and separate document
transfer, process CPU/RSS and database snapshots are retained. The 2026-10-19 local
sample passes the two-user ordinary p95<=2s/zero-error criterion; it does not establish
human acceptance or the production60m CPU request. Coverage and provisional values
are in `docs/synthetic-pilot.md` and `docs/evidence/2026-10-19-synthetic-sizing/`.
No deployment or publication is performed by these tools.

The follow-up container profile uses the owner Dockerfile at the existing 1000m CPU
and 1Gi memory limits: the same two-user mix passes locally with ordinary p95 of
0.412s and zero errors. It records cgroup throttling and memory separately from
PostgreSQL. This supports retaining those limits for this provisional scenario;
it does not validate a 60m reservation under contention or predict human demand.
Sampler gaps refuse sizing, and bounded cleanup applies on errors as well as success.


The named-operation profile `config/synthetic-pilot-phases.json` adds validated
operation dependencies, configurable ordering/frequency, persisted tender/lot/task
edits and derived request expectations. Startup, idle, ordinary, zero-think-time
burst, quiescent restart/readiness and recovery are now exercised locally at the
existing container limits. All 2971 operations passed in the retained phased run;
no human or production acceptance follows. Exact-release/hardware/shared-contention
follow-up is a live receiving task, RAPPS-WP-0014-T04 in railiance-apps, feeding
CUST-WP-0071-T02 and RESOURCE-WP-0008-T02.