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.