Docs/ARCHITECTURE.md

# ShopStack Architecture

> **Last updated:** 2026-06-15
> **Version:** 0.1.0
> **Purpose:** Comprehensive architectural reference for the ShopStack shopping intelligence platform.

---

## 1. System Overview

ShopStack is a **local-first, off-the-grid shopping intelligence platform** that helps households know what they have, what to use soon, what to buy, what to skip, and where to buy from — without sending data to the cloud.

### 1.1 Design Philosophy

| Principle | Application |
|-----------|-------------|
| **Local-first** | SQLite database (WAL mode), no cloud dependencies for core functionality |
| **Off-the-grid** | All mock providers by default; real models via optional local backends (MLX, llama.cpp) |
| **Decision-first** | Every workflow leads to a buy/skip/use-soon decision, not raw data |
| **Traceable** | Every tool execution creates an auditable trace with PII redaction |
| **Composable modules** | Six logical modules (ShopStock, ShopBasket, ShopCompare, etc.) share data through the same database |

### 1.2 Architecture Diagram

```
┌──────────────────────────────────────────────────────────────┐
│                     Gradio Blocks (app.py)                    │
│  13 tabs, workflow-header, custom CSS theme                   │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                  shopstack.ui.screens/                        │
│  dashboard.py  shopping.py  market_lens.py  inventory.py     │
│  ask.py  traces.py  other.py  price.py  model_stack.py       │
│  portability.py  household.py  field_notes.py  _utils.py     │
│  (Each screen is a Gradio adapter: parse → call → render)    │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                   shopstack.services/                         │
│  shopping.py  ─  shopping list normalization, classification, │
│                  Swiggy enrichment, list completion            │
│  market_lens.py ─  barcode scan, object detection, OCR, STT   │
│  dashboard.py  ─  today dashboard state assembly              │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                   shopstack.tools/registry.py                  │
│  11 tools: add/update/consume/move/find inventory items,      │
│  create shopping list, compare to inventory, record price,    │
│  use-soon, buy suggestions, export trace                      │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│               shopstack.persistence/database.py                │
│  SQLite + WAL mode, 10 tables, 18 seeded locations, full CRUD │
│  Tables: inventory_lots, purchase_events, shopping_lists,     │
│  shopping_list_items, household_locations, movement_events,   │
│  price_observations, stores, traces, app_config               │
│  Views: price_history, agent_traces (compat aliases)          │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                 shopstack.providers/                          │
│  registry.py ──  factory wired from Settings                  │
│  interfaces.py ──  11 abstract ABCs                          │
│  mock_providers.py ──  full mock implementations             │
│  local_provider.py ──  MLX + llama.cpp                       │
│  openai_provider.py ──  cloud fallback                       │
│  whisper_provider.py ──  cloud STT                           │
│  local_whisper_provider.py ──  on-device STT                 │
│  runtime.py ──  RuntimeReport dataclass                     │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│               shopstack.planner/                              │
│  engine.py ──  PlannerEngine orchestrates complete→parse→exec │
│  prompts.py ──  system prompt builder for tool-calling        │
│  parser.py ──  robust JSON + tool_call extraction             │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│                shopstack.market/                              │
│  schema.py ──  NormalizedMarketRecord, MarketSnapshot        │
│  normalization.py ──  size parser, unit prices, combo detect │
│  analytics.py ──  snapshot analytics, cheapest option finder │
│  basket.py ──  basket builder, canonical matching            │
│  metadata.py ──  produce shelf-life, waste-risk, storage     │
│  sources/swiggy.py ──  Swiggy loader, normalizer             │
└────────────────────────┬─────────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────────┐
│               Supporting modules                              │
│  decisions.py ──  7-class item decision engine (BUY/SKIP/...) │
│  portability.py ──  JSON/CSV export/import                   │
│  scanner.py ──  barcode decoding (pyzbar + zbarimg)          │
│  traces/export.py ──  PII redaction, JSONL export            │
│  model_registry.py ──  16 candidate model entries            │
│  module_registry.py ──  canonical module metadata            │
│  app_context.py ──  singleton wiring (db, tools, providers)  │
│  config.py ──  pydantic-settings, SHOPSTACK_ env prefix      │
└──────────────────────────────────────────────────────────────┘
```

---

## 2. Module Architecture

### 2.1 Module Map

| Module | Slug | Tabs | Dependencies | Service Paths |
|--------|------|------|--------------|---------------|
| **ShopStock** | `stock` | purchase, inventory, usesoon, map, portability | — | `screens.inventory`, `portability` |
| **ShopBasket** | `basket` | shopping | ShopStock | `services.shopping`, `screens.shopping` |
| **ShopCompare** | `compare` | prices | Sources | `market.analytics`, `market.normalization` |
| **ShopLens** | `lens` | market | ShopStock | `services.market_lens`, `screens.market_lens`, `scanner` |
| **ShopMemory** | `memory` | prices, notes | — | `ui.views`, `screens.other` |
| **ShopAgent** | `agent` | today, ask, trace | ShopStock, ShopBasket, ShopMemory | `planner.*`, `decisions`, `traces.export` |
| **Sources** | `sources` | (none) | — | `market.sources.swiggy` |
| **Runtime** | `runtime` | modelstack | — | `screens.model_stack`, `model_registry`, `providers.runtime` |

### 2.2 Module Registry (`shopstack/module_registry.py`)

All module metadata is defined in a single canonical registry. Every UI surface that needs module info (names, tab labels, dependencies, service paths) imports from this registry — never hardcodes strings.

Key data structures:
- `ModuleMetadata` dataclass (frozen) with slug, name, label, description, tab_ids, tab_labels, order, service_modules, depends_on, is_source
- `TAB_ORDER` dict — explicit ordering for the Gradio tab bar
- `TAB_LABELS` dict — canonical display names for every tab
- Lookup helpers: `get_by_slug()`, `get_by_tab_id()`, `tab_label()`, `tab_order()`, `navigation()`, `module_dependencies()`, `summary_table()`

---

## 3. Data Layer

### 3.1 Database (SQLite, WAL mode)

**Connection:** `check_same_thread=False` (safe for Gradio multi-threaded access)

**Tables:**

| Table | Purpose | Key Fields |
|-------|---------|------------|
| `inventory_lots` | Home inventory items | lot_id, canonical_name, quantity, unit, storage_location_id, status, price_paid, expiry dates |
| `purchase_events` | Purchase records | event_id, canonical_name, quantity, total_price, store_name, source_type |
| `shopping_lists` | Active shopping lists | list_id, name, goal, is_active |
| `shopping_list_items` | Items within lists | item_id, list_id, canonical_name, priority, status, linked_lots |
| `household_locations` | 18 seeded storage locations | location_id, name, parent_location_id, location_type |
| `movement_events` | Item location changes | movement_id, lot_id, from/to location, source, confidence |
| `price_observations` | Price history records | price_id, canonical_name, quantity, unit, price, store_name, observation_date |
| `stores` | Store metadata | store_id, name, location, store_type |
| `traces` | Workflow audit trail | trace_id, input_type, user_goal, perception, decision, proposed_tool_calls |
| `app_config` | Key-value config storage | key, value |

**Views (backward-compat aliases):**
- `price_history` → SELECT from `price_observations`
- `agent_traces` → SELECT from `traces`

**Location Hierarchy (18 seeded):**
```
Home
├── Kitchen
│   ├── Fridge
│   │   ├── Fridge Door
│   │   ├── Fridge Top Shelf
│   │   └── Fridge Vegetable Drawer
│   ├── Freezer
│   └── Pantry
│       ├── Pantry Top Shelf
│       ├── Pantry Middle Shelf
│       └── Spice Box
├── Bathroom
│   ├── Bathroom Cabinet
│   └── Under Bathroom Sink
├── Bedroom
│   └── Medicine Drawer
└── Balcony
    └── Balcony Cleaning Shelf
```

### 3.2 Pydantic Models (`shopstack/schemas/models.py`)

All domain models are Pydantic BaseModel classes in a single file:
- `InventoryLot`, `PurchaseEvent`, `DetectionEvent`, `OcrExtraction`
- `ShoppingList`, `ShoppingListItem`
- `VoiceCommand`, `ToolCall`, `Trace`
- `Store`, `PriceObservation`, `HouseholdLocation`, `MovementEvent`
- `TripWeatherContext`, `ItemCatalog`

**Key enums:** `Currency`, `ItemStatus`, `Priority`, `ListItemStatus`, `LocationType`, `SourceType`, `MovementSource`, `RuntimeMode`

**ID generation:** `uuid4().hex[:12]` — 12-char hex IDs throughout.

### 3.3 Configuration (`shopstack/config.py`)

pydantic-settings with `SHOPSTACK_` env prefix:

| Variable | Default | Purpose |
|----------|---------|---------|
| `SHOPSTACK_DB_PATH` | `data/shopstack.db` | Database file path |
| `SHOPSTACK_APP_PORT` | `7860` | Gradio server port |
| `SHOPSTACK_OFF_THE_GRID` | `true` | Use mock providers (no cloud) |
| `SHOPSTACK_PLANNER_BACKEND` | `mock` | Text generation/planning |
| `SHOPSTACK_STT_BACKEND` | `mock` | Speech-to-text |
| `SHOPSTACK_TTS_BACKEND` | `mock` | Text-to-speech |
| `SHOPSTACK_VISION_BACKEND` | `mock` | Vision/object detection |
| `SHOPSTACK_OCR_BACKEND` | `mock` | OCR |
| `SHOPSTACK_SEGMENTATION_BACKEND` | `mock` | Segmentation |
| `SHOPSTACK_LOCAL_MODEL_REPO` | `unsloth/Llama-3.2-3B-Instruct-GGUF` | Local model source |
| `SHOPSTACK_LOCAL_WHISPER_SIZE` | `tiny` | Local whisper model size |
| `SHOPSTACK_OPENAI_API_KEY` | `""` | Cloud fallback key |

---

## 4. Provider System

### 4.1 Provider Interfaces (`shopstack/providers/interfaces.py`)

11 abstract provider ABCs, each defining a capability:

| Interface | Key Methods | Mock Behavior |
|-----------|-------------|---------------|
| `STTProvider` | `transcribe(audio_path)` | Returns predefined Hindi/Hinglish phrases |
| `TTSProvider` | `speak(text)` | Writes note about what would be spoken |
| `VisionProvider` | `analyze(image_path, prompt)` | Random samples from 26 common kitchen items |
| `ObjectDetectionProvider` | `detect(image_path)` | Plausible bounding boxes + confidences |
| `GroundingProvider` | `ground(image_path, text)` | Returns grounded item references |
| `SegmentationProvider` | `segment(image_path)` | Returns placeholder masks |
| `OCRProvider` | `extract_text(image_path)` | Returns mock extracted text |
| `PlannerProvider` | `plan(context)` | Returns structured multi-step plans |
| `ToolCallParserProvider` | `parse(response_text)` | Parses intent → tool call candidates |
| `EmbeddingsProvider` | `embed(texts)` | Returns random 384-d vectors |
| `ImageEditProvider` | `edit(image_path, prompt)` | Returns a dummy edited image path |

### 4.2 Provider Registry (`shopstack/providers/registry.py`)

The `ProviderRegistry` is a factory wired from Settings:
- Reads `SHOPSTACK_*_BACKEND` env vars
- Backend `"mock"` → Mock*Provider (default)
- Backend `"local"` → `LocalProvider` (MLX or llama.cpp)
- Backend `"openai"` → `OpenAIProvider` (cloud)
- Backend `"local_whisper"` → `LocalWhisperProvider`
- Falls back gracefully to mock if a real backend isn't available

### 4.3 Runtime Report (`shopstack/providers/runtime.py`)

`RuntimeReport` dataclass captures:
- Provider name, backend, loaded status, capability count
- Error state if provider failed to init
- Used by the Model Stack UI tab

---

## 5. Tool System

### 5.1 Tool Registry (`shopstack/tools/registry.py`)

11 tools, each registered with name, description, args schema, and handler:

| Tool | Args | Purpose |
|------|------|---------|
| `add_inventory_item` | canonical_name, display_name, quantity, unit, storage_location, category, purchase_date, price_paid | Add new item to inventory |
| `update_inventory_item` | lot_id, updates dict | Update existing inventory item |
| `consume_inventory_item` | lot_id, quantity | Record consumption (partial or full) |
| `move_inventory_item` | lot_id, to_location, from_location | Move item between storage locations |
| `find_item` | name (prefix search) | Search inventory across names & locations |
| `create_or_update_shopping_list` | goal, items list | Create/update the active shopping list |
| `compare_visible_item_to_inventory` | item_name | Compare detected item against current stock |
| `record_price_observation` | canonical_name, price, quantity, unit, store_name | Record a price observation |
| `get_use_soon_items` | days (default 3) | Get items expiring or aging soon |
| `get_next_buy_suggestions` | — | Get suggestions for what to buy next |
| `export_anonymized_trace` | trace_id | Export an anonymized agent trace |

---

## 6. Decision Engine (`shopstack/decisions.py`)

Every household item is classified into one of 7 categories:

| Decision | Color | When |
|----------|-------|------|
| `BUY` | Green | Out of stock or running low, and needed |
| `SKIP` | Gray | Already have enough, recently bought, or high waste risk |
| `USE_SOON` | Amber | Existing stock is expiring or aging |
| `OPTIONAL` | Blue | Not urgent, good-to-have |
| `COMPARE` | Purple | Needs price/store/pack comparison |
| `CONFIRM` | Red | Uncertain data, needs human verification |
| `WATCH` | Light Gray | Not urgent, monitor |

**Classification logic (`_classify()`):**
1. If item is `use_soon` AND `quantity > 0` → USE_SOON
2. If `low_stock` AND `quantity <= 0` → BUY
3. If `low_stock` AND `quantity > 0` → BUY
4. If `on_list` AND `quantity > 0` → SKIP (already have)
5. If `quantity > 0` AND well stocked → SKIP
6. Default → WATCH

**Data sources for classification:**
- Active inventory (DB)
- Use-soon items (3-day threshold)
- Active shopping list items
- Recent purchase events (2-day window)
- Market snapshot prices (Swiggy)
- Produce metadata (shelf life, waste risk)

---

## 7. Market Intelligence System

### 7.1 Data Flow

```
Swiggy Instamart snapshot (CSV/JSON)
  → market/sources/swiggy.py (load + normalize)
    → market/schema.py (NormalizedMarketRecord, MarketSnapshot)
      → domain/unit_price.py (size parser, unit prices, combo detection)
        → market/analytics.py (price stats, cheapest finder)
          → Services (shopping.py enrichment, dashboard.py)
            → UI Screens (other.py swiggy views, shopping.py cards)
```

### 7.2 Normalization Pipeline (`domain/unit_price.py`)

Canonical business logic for size/unit normalization lives in `shopstack/domain/unit_price.py`.
The original `market/normalization.py` is now a thin re-export shim (motto_v3 §7).

Raw Swiggy records are normalized through:
1. **Size parsing** (`parse_size`) — extracts numeric quantity and unit from text like "500 g", "1 kg"
2. **Unit price calculation** (`compute_unit_prices`) — per-kg for weight-based, per-L for volume, per-unit for piece items
3. **Canonical name mapping** (`resolve_canonical`, `CANONICAL_MAP`) — e.g., "Fresh Tomatoes (Hybrid)" → "tomato"
4. **Combo detection** (`canonicalize_name`) — identifies multi-pack/assorted items

### 7.3 Produce Metadata (`market/metadata.py`)

Lookup table for ~80 common produce items with:
- Shelf life in days
- Waste risk (high/medium/low)
- Storage recommendations
- Use-first priority ranking

### 7.4 Basket Builder (`market/basket.py`)

Matches user item requests against available market records using:
- Canonical name matching
- Quantity/unit estimation
- Cheapest option selection
- Summary with total estimate

---

## 8. Planner System

### 8.1 Planner Engine (`shopstack/planner/engine.py`)

`PlannerEngine` orchestrates:
1. **Build prompt** — system prompt + tool definitions + user question
2. **Get completion** — calls ProviderRegistry planner backend
3. **Parse response** — extracts JSON tool calls from LLM output
4. **Execute tools** — runs through ToolRegistry, collects results
5. **Format response** — human-readable output

### 8.2 Parser (`shopstack/planner/parser.py`)

Robust JSON extraction from LLM output:
- Finds ````json` blocks
- Falls back to regex for `[{"tool":...,"args":{...}}]` patterns
- Returns empty list on failure (graceful degradation)

### 8.3 Prompts (`shopstack/planner/prompts.py`)

System prompt builder that generates tool-calling instructions including:
- Current inventory state summary
- Available tools with arg schemas
- Usage examples
- Output format constraints

---

## 9. UI Architecture

### 9.1 Gradio Tab Structure

13 tabs, wired in `app.py` using `module_registry.tab_label()` for canonical names:

| Tab ID | Display Label | Screen Module | Key Functions |
|--------|--------------|---------------|---------------|
| `today` | Today | `screens/dashboard.py` | `today_dashboard()` — 6-value return |
| `ask` | Ask ShopStack | `screens/ask.py` | `ask_shopstack()`, voice add commands |
| `shopping` | Shopping List | `screens/shopping.py` | Create/view/classify/complete lists |
| `market` | Market Lens | `screens/market_lens.py` | Scan, compare, buy/skip decisions |
| `purchase` | Add Purchase | `screens/inventory.py` | Form + batch purchase recording |
| `inventory` | Find Item at Home | `screens/inventory.py` | Search, cards, consume |
| `usesoon` | Use Soon | `screens/inventory.py` | Expiry alerts, consume batch |
| `prices` | Price Memory Check | `screens/price.py` | Price history, intelligence |
| `map` | Map | `screens/other.py` | Location view, move items |
| `modelstack` | Model Stack | `screens/model_stack.py` | Budget, provider status |
| `trace` | Traces | `screens/traces.py` | List, detail, export |
| `portability` | Data | `screens/portability.py` | JSON/CSV export/import |
| `notes` | Field Notes | `screens/field_notes.py` | Markdown editor |

### 9.2 UI Components (`shopstack/ui/components/cards.py`)

HTML rendering helpers:
- `badge_html()` — colored status badges
- `card()` — styled card with header/body
- `empty_state()` — empty state message
- `render_rows()` — HTML table rows from dicts
- `render_decision_card()` — decision with color-coded badge
- `render_grouped_cards()` — grouped decision cards
- `render_metric()` — metric display

### 9.3 UI Views (`shopstack/ui/views.py`)

Dataclass-returning view builders:
- `PriceMemoryView` — price history data + chart info
- `FieldNotesView` — field notes load/save
- `build_price_memory_view()` — assembles price history + chart DataFrame

### 9.4 Error Boundary (`shopstack/ui/screens/_utils.py`)

`@safe_render` decorator catches exceptions in UI render functions and returns a graceful error HTML message instead of crashing the tab.

---

## 10. Service Layer

### 10.1 Shopping Service (`shopstack/services/shopping.py`)

| Function | Purpose |
|----------|---------|
| `normalize_item_name(name)` | Normalize item names (lowercase, strip) |
| `classify_shopping_items(items, tools)` | Classify items via LLM (buy/skip/use-soon) |
| `enrich_items_with_swiggy(items)` | Add Swiggy price/availability data |
| `complete_shopping_list_service(list_id, tools)` | Complete list → add to inventory |
| `mark_items_purchased_service(item_ids_json, tools)` | Mark items purchased |

### 10.2 Market Lens Service (`shopstack/services/market_lens.py`)

| Function | Purpose |
|----------|---------|
| `analyze_market_lens(image_path, audio_path, providers, tools)` | Full pipeline: detect → compare → decide |
| `detect_barcodes(image_path)` | Decode barcodes from image |
| `analyze_visible_items(image_path, providers, tools)` | Object detection + inventory comparison |
| `enrich_market_prices(decisions)` | Add Swiggy price data to decisions |
| `transcribe_audio(audio_path, providers)` | Speech-to-text |

### 10.3 Dashboard Service (`shopstack/services/dashboard.py`)

| Function | Purpose |
|----------|---------|
| `build_dashboard_state(db, tools)` | Assemble full dashboard state: inventory stats, use-soon, market basket, low-stock, recent purchases |

---

## 11. Model Registry (`shopstack/model_registry.py`)

16 candidate model entries across 7 provider groups.

**Parameter budget:** ≤32B total active params (enforced by `validate_active_model_budget()`).

### Active Models:

| Model | Group | Params | Runtime | Backend Config |
|-------|-------|--------|---------|----------------|
| `llama-3.2-3b-instruct` (MLX) | Planner | 3.0B | mlx | `PLANNER_BACKEND=local` |
| `llama-3.2-3b-gguf` | Planner | 3.0B | gguf | (llama.cpp fallback) |
| `local-whisper-tiny` (MLX) | STT | 0.04B | mlx | `STT_BACKEND=local_whisper` |

**Total active: ≤6.04B params** — well within 32B cap.

---

## 12. Trace System (`shopstack/traces/export.py`)

Every tool execution creates an agent trace stored in the database. Traces include:
- Perception snapshots
- Inventory context before/after
- Decision rationale
- Proposed tool calls
- Human confirmation status

**PII Redaction:** Phone numbers (10+ digits), emails, Aadhar (12-digit), PAN (5+4+1), addresses. Generic `name` fields are preserved.

**Export:** JSONL format via `export_traces()`.

---

## 13. Portability (`shopstack/portability.py`)

- **JSON export:** Full inventory + price observations + purchase events + field notes
- **CSV export:** Inventory items only
- **JSON import:** Inventory + price observations + field notes (with dedup)
- **CSV import:** Inventory items only (with dedup)
- **Schema version:** 1.0

---

## 14. CI/CD

GitHub Actions workflow (`.github/workflows/ci.yml`):
- Runs on push/PR to main
- Sets up Python 3.13
- Installs dependencies in dev mode
- Runs full test suite
- Runs benchmark suite

Pre-commit hook runs `tools/sync-readme-stats` to keep README test counts current.

---

## 15. Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| **Single schemas file** | Models share enums; avoid circular imports |
| **Provider ABCs named *Provider** | Clear naming convention prevents confusion |
| **PurchaseEvent with per-item fields** | No separate join table for simple purchases |
| **12-char hex IDs** | Short enough for prefix resolution, collision-resistant |
| **WAL mode** | Concurrent read/write safe for Gradio |
| **18 seeded locations** | Hierarchical, covers typical Indian household |
| **No auto-purchase/payment scraping** | Design-level constraint; ShopStack advises, doesn't buy |
| **PII redaction targeted** | Only phone/email/Aadhar/PAN/address; generic names preserved |
| **Mock providers as default** | Full app works without any ML model loaded |
| **`_env_file=None` in tests** | Prevents `.env` from affecting test results |
| **shopstack.ui package** | All render logic consolidated; no orphan modules |
| **service boundary extraction** | Product logic lives in services/; screens are Gradio adapters |
| **module_registry canonical names** | No hardcoded tab labels anywhere in app.py |

---

## 16. Future Architecture Targets

| Area | Planned Approach | Status |
|------|------------------|--------|
| **Cloud inference fallback** | HF Inference API provider | Built in `providers/huggingface_provider.py` (26 tests) |
| **Modal cloud GPU** | Modal provider for heavy models | Built in `providers/modal_provider.py` |
| **Semantic search** | BGE-M3 + Nomic embeddings | Both providers built in `providers/embeddings_provider.py`. Default is Nomic (config: `embeddings_backend=nomic`). Wired into `services/search.py` + `services/find.py`. |
| **Receipt scanning** | OCR pipeline → purchase creation | Pipeline built: `services/ocr_pipeline.py` (3-stage) + `services/receipt.py` (full pipeline). OCR provider, Tesseract provider, and dedicated receipt screen exist. |
| **Multi-retailer sources** | Blinkit, Zepto, DMart adapters | All 4 built: Swiggy `_swiggy_adapter.py`, Blinkit `_blinkit_adapter.py`, Zepto `_zepto_adapter.py`, DMart `_dmart_adapter.py`. Cross-source comparison in `_comparison.py`. |
| **Correction review UI** | Accept/reject corrections | Built: dedicated `ui/screens/corrections.py` (264 lines), wired into Memory tab, per-row inline accept/reject buttons, DB `correction_events` table. |
| **Multi-user auth** | user_id columns exist in DB | Not started |
| **Production deployment** | Docker + deployment config | Not started |