Initial commit: project description

README.md

@@ -0,0 +1,62 @@
+# radar-contratos
+
+**Procurement red-flag analyzer — "follow the money" for Portuguese public contracts**
+
+> Status: early planning. Loose project description; scope and architecture still being worked out.
+
+## The idea
+
+All public contracts in Portugal are published on **`base.gov.pt`** (Portal BASE), as
+required by the Código dos Contratos Públicos. The data is public — but the portal is
+useless for *analysis*. The value is in turning that compliance data into **accountability
+signals**.
+
+The wedge is narrow on purpose: **one lens, done well** — flag patterns around
+**`ajuste direto`** (direct award without real competition):
+
+- **Contract-splitting** — multiple awards to the same supplier kept just under the
+  legal value threshold to avoid an open tender.
+- **Repeat winners** — the same supplier repeatedly awarded by the same contracting
+  entity, especially via direct award.
+- **Timing spikes** — award bursts before elections or at fiscal year-end.
+- **Concentration** — share of an entity's spend going to its top N suppliers.
+
+Journalist-bait, citizen-legible, and an **uncontested *analysis* moat**: the data is
+open, but nobody packages the red flags.
+
+## Prior art / why this isn't redundant
+
+- **`base.gov.pt`** itself: has search + some entity-relationship features + annual PDF
+  reports, but **no red-flag / pattern / network analysis** and a clunky UI. The data is
+  the commodity; the analysis layer is the gap.
+- Context: in a recent year, `ajuste direto` was the single most frequent procedure type
+  (>112k direct awards). Plenty to analyze.
+
+## Ratings (re-derived)
+
+- **Effort to MVP:** weeks (data ingest is the work; analyses start simple)
+- **Upkeep:** low–moderate (periodic re-ingest; analyses are mostly static logic)
+- **Money:** none / grants — public good
+- **Fit:** high — accountability gravitas, high citation potential, reuses civic pipeline
+
+## Design principles
+
+- **Signpost, not accusation.** A red flag is a *question*, not a verdict — always link to
+  the underlying contract on base.gov.pt; "isto não é uma acusação" framing.
+- **One lens deep** before breadth. Ship the `ajuste direto` analysis fully before adding
+  concursos, suppliers networks, etc.
+
+## Open questions (to resolve before building)
+
+- **Data access:** bulk download vs. scraping base.gov.pt; is there a usable export / open
+  dataset on dados.gov.pt, or do we replay the portal's backend calls?
+- **Thresholds:** current legal value thresholds for ajuste direto / consulta prévia, and
+  how they've changed over time (needed to detect splitting correctly).
+- **Entity identity:** matching suppliers/entities across records (NIF as key; name variants).
+
+## Relation to siblings
+
+Shares the **scrape → store → classify → present** skeleton with
+[`o-que-mudou`](../o-que-mudou). Cross-referencing winners against political donations /
+beneficial ownership / declared interests is a *later* idea (its own project), explicitly
+**out of scope** for this MVP.