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 |

---

## 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)
- Multi-tenancy
- 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; no CI workflow configured yet
  (`.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, D1/A1/C0/R0 as of the initial coverage sweep —
low discovery confidence pending this SCOPE.md's first real fill-in).

---

## 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.