From 1991bc2e09c1a8f323cfbd9aeb9641c0e50ee949 Mon Sep 17 00:00:00 2001 From: Jun-te Kim Date: Tue, 26 May 2026 10:20:29 +0000 Subject: [PATCH] landlord overrides --- CONTEXT.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index 4a95696..7a79d1c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -31,6 +31,20 @@ _Avoid_: aggregator, merger The terminal action that reads the combiner output, inserts rows as Properties on the Portfolio, and decides whether the BulkUpload needs further review. _Avoid_: import, commit, ingest +### Landlord overrides + +**Landlord**: +The housing association supplying a Portfolio's BulkUploads. A Landlord knows facts about their properties that EPC data doesn't (e.g. that a cavity has been filled), and those facts take precedence when computing an assessment. +_Avoid_: customer, client, owner, organisation (Organisation is a separate, broader entity) + +**Landlord override**: +A landlord-supplied fact about a property that takes precedence over EPC-derived defaults when computing an assessment. The end-to-end Landlord override journey has two layers — a **VocabularyMapping** layer (this glossary entry below) and a per-Property fact layer (not yet modelled). +_Avoid_: customer data, manual override, landlord data + +**VocabularyMapping**: +The translation from a Landlord's free-text description in a BulkUpload column (e.g. `"cavity: filledcavity"`) to a canonical domain enum value (e.g. `WallType.CAVITY`). Produced by a `ColumnClassifier` (today an LLM, tomorrow possibly a lookup table or rules engine) in the Model service. Stored per-Portfolio, one row per `(category, description)`. A row carries provenance (`classifier` or `user`) so user overrides survive re-classification. +_Avoid_: column mapping (that's a separate concept — see `ColumnMapping` above), classification, dictionary + ## Lifecycle A **BulkUpload** moves through these statuses: @@ -58,6 +72,7 @@ See [ADR-0001](./docs/adr/0001-bulk-upload-state-machine.md) for the deliberate - A **Portfolio** has many **BulkUploads**. - A **BulkUpload** produces zero or more **Properties** when finalised. - A **BulkUpload** has at most one **Task** (the orchestration handle for the FastAPI pipeline run); a Task has many **SubTasks** (one per pipeline stage: address matching, combiner). +- A **Portfolio** has many **VocabularyMappings** — one row per `(category, description)` it has ever encountered across all its BulkUploads. See [ADR-0002](./docs/adr/0002-landlord-override-vocabulary.md). ## Example dialogue