Wine Platform Architecture¶

Overview¶

The Wine Platform is a hybrid system combining manual inventory management and automated vision-based stock detection.

The system runs primarily on a Raspberry Pi, uses a Synology NAS for shared operational data, and supports Mac-based maintenance and development workflows.

The architecture is intentionally separated into several domains:

Domain	Responsibility
Manual Lane	Kiosk-based inventory management
Vision Lane	Automated bottle detection pipeline
Code Repository	Application source and services
Data Repository	Images, models, and runtime artifacts
Calibration Tools	Shelf geometry and mask preparation

This separation improves:

maintainability
operational reliability
reproducibility of vision results
resilience to device rebuilds

High-Level System Architecture¶

flowchart LR

USER["Operator"]

MAC["Mac Workstation
Calibration / debugging / docs"]

PI["Raspberry Pi
Application runtime"]

NAS["Synology NAS
Shared data"]

USER --> PI
MAC <-->|SMB| NAS
PI <-->|NAS mount| NAS
MAC <-->|SSH / Git / VSCode| PI

System Domains¶

The platform is divided into two main operational lanes.

Manual Lane¶

The manual lane supports daily cellar operations.

Functions include:

goods movements
material master management
manual inventory adjustments
shelf browsing
ROI calibration

Primary components:

apps/winecellar/frontend
apps/winecellar/backend

Main interface:

Qt Kiosk UI on Raspberry Pi touchscreen

Vision Lane¶

The vision lane automatically monitors cellar stock.

It performs:

snapshot capture
perspective rectification
cell cropping
bottle-end detection
inventory comparison

Primary code location:

workers/wine_inventory/src/pince_shelf

Repository vs Data Separation¶

One of the most important design principles of the system is the separation between code and data.

Code Repository¶

Location on Raspberry Pi:

/home/pi/wine_platform

Contains:

application code
backend services
kiosk UI
vision workers
configuration logic
documentation
tools

The repository defines how the system works.

Shared Data Repository¶

Location on Synology NAS:

/volume2/web/web_images/Stock_vision

Mounted on Raspberry Pi as:

/mnt/nasWeb/web_images/Stock_vision

Contains:

snapshots
models
crop outputs
detection results
proposals
debug artifacts

The data repository records what the system processes and produces.

Manual Lane Architecture¶

flowchart LR

KIOSK["Qt Kiosk UI"]

API["FastAPI Backend"]

DB["MariaDB
Synology NAS"]

CFG["Shared Configuration"]

KIOSK --> API
KIOSK --> CFG
API --> DB
API --> CFG

The manual lane enables operators to manage cellar inventory through a touch-friendly kiosk interface.

Primary user actions include:

registering goods movements
browsing wines
checking shelf contents
performing inventory adjustments

Vision Lane Architecture¶

flowchart TD

TRIGGER["Motion detection
or scheduled run"]

SNAP["take_clean_snapshot.py"]

RECTIFY["Shelf rectification"]

CROP["crop_with_json.py"]

DETECT["onnx_batch.py"]

COMPARE["DB_compare.py"]

TRIGGER --> SNAP
SNAP --> RECTIFY
RECTIFY --> CROP
CROP --> DETECT
DETECT --> COMPARE

This pipeline runs automatically and produces vision-derived stock estimates.

The results are compared against database quantities to detect discrepancies.

Calibration Workflow¶

Calibration is a manual maintenance procedure used when camera geometry changes.

Typical triggers include:

camera repositioning
shelf modification
degraded detection accuracy

Calibration includes:

ROI corner selection
mask preparation
ROI adjustment
validation

flowchart TD

ROI["ROI Calibration UI"]

MASK["Manual mask drawing"]

ROIADJ["ROI_Adjustment_from_PNG.py"]

MASKGEN["generate_mask_for_polc.py"]

CONFIG["Persisted geometry config"]

ROI --> CONFIG
MASK --> ROIADJ
ROIADJ --> CONFIG
MASKGEN --> CONFIG

Production pipelines only read calibration results.

They never modify them.

Deployment Architecture¶

flowchart LR

PI["Raspberry Pi"]

API["Backend API"]
KIOSK["Qt Kiosk"]
WORKERS["Vision Workers"]

NAS["Synology NAS"]

DB["MariaDB"]

PI --> API
PI --> KIOSK
PI --> WORKERS

API --> DB
WORKERS --> NAS
API --> NAS

The Raspberry Pi acts as the primary runtime host, while the NAS provides:

persistent storage
database services
shared files

Development and Maintenance Environment¶

A Mac workstation is commonly used for:

mask drawing
ROI adjustments
debugging vision outputs
editing documentation
developing code via VS Code

flowchart LR

MAC["Mac"]

NAS["NAS shared data"]

PI["Raspberry Pi code"]

MAC --> NAS
MAC --> PI

Documentation Map¶

The documentation is organized into several areas.

Architecture¶

Explains system structure and design.

Key pages include:

Repository and Data Layout
Repository and Data Architecture
System Architecture (this page)

Flows¶

Describes operational workflows:

Manual lane:

Kiosk overview
Movements
Materials
Inventory
Shelf interaction
ROI calibration

Vision lane:

Motion-triggered pipeline
Scheduled pipeline
Snapshot acquisition
Cropping
Detection
Inventory comparison

Operations¶

Operational guidance for running the system:

services
configuration
path management
deployment

Mental Model¶

A useful way to think about the system:

flowchart LR

CODE["Repository
logic + workflows"]

DATA["NAS storage
images + outputs"]

OPER["Operator workflows"]

VISION["Automated vision"]

OPER --> CODE
VISION --> CODE
CODE --> DATA
VISION --> DATA

The repository defines the logic of the system, while the data repository records the operational artifacts of its execution.

Summary¶

The Wine Platform architecture is based on clear separation of responsibilities:

Component	Role
Raspberry Pi	executes application and vision workers
Synology NAS	stores persistent operational data
Qt kiosk	manual inventory management
Vision pipeline	automated bottle detection
Calibration tools	maintain geometric references
Mac workstation	comfortable development and maintenance

This modular design ensures the system remains:

maintainable
scalable
robust
auditable

even as the platform evolves.