Skip to content

Wine Platform — Home Assistant Validation Integration

Purpose

This document describes the human validation layer of the Wine Platform.

The vision pipeline detects bottle quantities in storage bins.
If a mismatch is detected between the vision count and the database inventory, the system creates a movement proposal instead of modifying the database automatically.

The proposal is sent to Home Assistant, where the user can:

  • review the snapshot
  • see the wines stored in the bin
  • approve or reject the correction

This ensures safe inventory updates with human verification.

System Architecture

Vision pipeline generates bottle counts.

If a difference is detected:

Vision pipeline
↓
DB_compare.py
↓
POST /vision/proposals
↓
FastAPI backend
↓
notify_home_assistant_new_proposal()
↓
Home Assistant webhook
↓
HA automation updates helpers
↓
Validation dashboard
↓
Approve / Reject decision
↓
Backend inventory movement

Backend Components

Router

File:

apps/winecellar/backend/app/routers/vision_proposals.py

Responsibilities:

  • creating proposals
  • retrieving proposals
  • approving proposals
  • rejecting proposals

POST /vision/proposals

Creates a proposal when the vision pipeline detects a mismatch.

Example payload:

{ "bin_code": "03_03", "quantity_difference": -1, "snapshot_path": "/local/wine/03_03.png" }

Workflow:

  1. store proposal in database
  2. retrieve DB contents of the bin
  3. enrich proposal with wine information
  4. send notification to Home Assistant

GET /vision/proposals

Returns proposals stored in the database.

Used for:

  • debugging
  • monitoring
  • system administration

POST /vision/proposals/{proposal_id}/approve

User confirms the difference.

Backend actions:

  • create inventory movement
  • update stock quantities
  • mark proposal as approved

POST /vision/proposals/{proposal_id}/reject

User rejects the proposal.

Backend actions:

  • mark proposal rejected
  • do not modify inventory

Proposal Service

Proposal logic is implemented in the service layer.

Example function:

create_movement_proposal()

Responsibilities:

  1. store proposal
  2. retrieve wines in bin
  3. calculate DB totals
  4. enrich proposal data
  5. notify Home Assistant

Retrieving Wines in Bin

The backend queries:

GET /bins/{st_bin}/wines

Example result:

{ "items": [ { "ref": 136, "description": "Chablis", "year": 2022, "region": "Burgundy", "bcode": "CHAB22", "label": "/web_images/Label/0136_label.jpg", "qty": 3 } ] }

The service converts this into:

bin_details ├─ wine_count ├─ total_db_qty └─ items

Home Assistant Integration

The backend sends a webhook to Home Assistant.

Example payload:

{ "id": 999, "bin_code": "03_03", "quantity_difference": -1, "snapshot_path": "/local/wine/03_03.png", "status": "pending", "created_at": "2026-03-12T10:00:00", "bin_details": { "wine_count": 2, "total_db_qty": 5, "items": [...] } }

Image Storage

Snapshots are stored on the Synology NAS.

Example path:

/volume2/web/web_images/Stock_vision/data/cells_runtime_res/

Example file:

03_03.png

Synology Container Bind Mount

To allow Home Assistant to display images:

NAS folder:

/volume2/web/web_images/Stock_vision/data/cells_runtime_res

Mounted into container:

/config/www/wine

Home Assistant exposes /config/www as:

/local/

Resulting URL:

/local/wine/03_03.png

Home Assistant Configuration

Home Assistant runs as a Docker container on Synology.

Configuration directory:

/volume1/docker/homeassistant/config

Important files:

configuration.yaml
automations.yaml
scripts.yaml
rest_commands.yaml

Required Helpers

Home Assistant stores proposal state in helpers.

input_text.wine_proposal_id
input_text.wine_proposal_bin
input_text.wine_proposal_image
input_text.wine_proposal_status
input_text.wine_proposal_created_at
input_text.wine_proposal_last_action
input_text.wine_proposal_bin_details
input_number.wine_proposal_diff
input_boolean.wine_proposal_pending

Webhook Automation

Automation listens for proposals:

/api/webhook/inventory-post-J2flmsgFU3p87UZTLE5KoIVu

The automation:

  1. updates helpers
  2. stores proposal information
  3. sends mobile notification

Validation Dashboard

The Home Assistant dashboard displays:

  • proposal information
  • bin snapshot
  • wines stored in bin
  • approve/reject buttons
  • debug helpers

Approve / Reject Scripts

Scripts call backend REST endpoints.

Approve:

POST /vision/proposals/{id}/approve

Reject:

POST /vision/proposals/{id}/reject

Result

This system provides a human-verified inventory correction workflow.

Benefits:

  • prevents incorrect AI corrections
  • enables visual verification
  • keeps database consistent
  • provides full traceability