Skip to content

Repository and Data Architecture

Overview

The Wine Platform is distributed across multiple physical and logical environments.

The architecture is intentionally split between:

  • code execution on the Raspberry Pi
  • shared operational data on the Synology NAS
  • visual/manual maintenance work from a Mac
  • manual lane via Qt kiosk
  • automated lane via vision workers

This document explains how these environments relate to each other and why the separation between code and data is essential.

1. System Landscape

flowchart LR

MAC["Mac
Visual tools / calibration / documentation"]

PI["Raspberry Pi
Main runtime host"]

NAS["Synology NAS
Shared data storage"]

MAC <-->|SMB mount| NAS
PI <-->|NAS mount| NAS
MAC <-->|SSH / VS Code / Git / editing| PI

2. Main Architectural Split

flowchart TD

CODE["Code Repository
/home/pi/wine_platform"]

DATA["Shared Data Repository
/volume2/web/web_images/Stock_vision
or
/mnt/nasWeb/web_images/Stock_vision"]

CODE --> MANUAL["Manual Lane
Qt kiosk + backend"]

CODE --> AUTO["Automated Vision Lane
workers / pipelines"]

AUTO --> DATA
MANUAL --> DATA

This is the central architectural principle of the project:

  • the repository contains logic
  • the data tree contains artifacts and evidence

3. Raspberry Pi Runtime Architecture

flowchart TD

PI["Raspberry Pi"]

subgraph CODE["/home/pi/wine_platform"]
APPS["apps/winecellar"]
WORKERS["workers/wine_inventory"]
SHARED["shared"]
DOCS["docs"]
TOOLS["tools"]
SYSTEMD["systemd"]
end

PI --> CODE

The Pi is the main execution host for the application code.

It runs:

  • the kiosk frontend
  • the backend API
  • the automated vision workers
  • scheduled and event-driven processing
  • local service orchestration

4. Manual Lane on Raspberry Pi

flowchart LR

subgraph ManualLane["Manual Lane"]
QT["Qt Kiosk Frontend"]
API["FastAPI Backend"]
CFG["Shared Config"]
end

QT --> API
QT --> CFG
API --> CFG

The manual lane lives mainly inside the code repository and supports:

  • goods movements
  • material master
  • inventory workflows
  • shelf interaction
  • calibration entry points

This lane is mostly user-facing.

5. Automated Vision Lane on Raspberry Pi

flowchart LR

subgraph VisionLane["Automated Vision Lane"]
TRIG["Triggers
Motion / Scheduled"]
SNAP["Snapshot + Rectification"]
CROP["Crop Generation"]
ONNX["Bottle-End Detection"]
CMP["DB Compare"]
end

TRIG --> SNAP
SNAP --> CROP
CROP --> ONNX
ONNX --> CMP

This lane is the machine-vision execution path.

It depends on:

  • code from the Pi repo
  • shared configuration
  • runtime data stored on the NAS-backed data area

6. Synology NAS Data Architecture

flowchart TD

NAS["Synology NAS"]

subgraph STOCK["/volume2/web/web_images/Stock_vision"]
MODELS["data/models"]
SNAPS["data/snapshots"]
CROPS["data/cells_runtime"]
RESULTS["data/cells_runtime_res"]
PROPOSALS["data/proposals"]
end

subgraph OTHER["Sibling areas"]
LABEL["Label"]
DOCS["docs"]
end

NAS --> STOCK
NAS --> OTHER

The NAS stores the persistent operational data used by the vision system.

This includes:

  • trained models
  • snapshots
  • crop results
  • detector outputs
  • proposals
  • evidence
  • label images

7. Code-to-Data Relationship

flowchart TD

CODE["Pi Code Repository"]

SNAPMOD["take_clean_snapshot.py"]
CROPMOD["crop_with_json.py"]
ONNXMOD["onnx_batch.py"]
DBMOD["DB_compare.py"]

DATA["NAS Data Repository"]

RECT["shelf_rectified.jpg"]
POLY["cells_polygons.json"]
CROPS["cell crop PNGs"]
CSV["results.csv"]
DIFF["diff_only.json / diff_only.csv"]

CODE --> SNAPMOD
CODE --> CROPMOD
CODE --> ONNXMOD
CODE --> DBMOD

SNAPMOD --> RECT
CROPMOD --> POLY
CROPMOD --> CROPS
ONNXMOD --> CSV
DBMOD --> DIFF

RECT --> DATA
POLY --> DATA
CROPS --> DATA
CSV --> DATA
DIFF --> DATA

This shows the fundamental relationship:

  • code modules live in the repository
  • outputs produced by those modules live in the shared data tree

8. Mac as Visual Operations Workstation

flowchart LR

MAC["Mac"]

subgraph VisualWork["Visual / Maintenance Tasks"]
MASK["Mask drawing"]
ROI["ROI adjustment"]
DEBUG["Debug image inspection"]
DOC["Documentation editing"]
end

NAS["NAS shared data"]
PI["Pi source repo"]

MAC --> VisualWork
VisualWork --> NAS
MAC --> PI

The Mac is especially useful for tasks that are awkward on the small Pi touchscreen, such as:

  • drawing blue mask lines
  • reviewing rectified shelf images
  • adjusting ROI polygons
  • inspecting debug outputs
  • writing documentation

This is one reason the project supports path resolution across Pi, NAS, and Mac environments.

9. Same Data, Different Filesystem Roots

flowchart TD

DATA["Shared logical dataset"]

NASP["Synology path
/volume2/web/web_images/Stock_vision"]

PIP["Pi mount path
/mnt/nasWeb/web_images/Stock_vision"]

MACP["Mac SMB path
/Volumes/web/web_images/Stock_vision"]

DATA --> NASP
DATA --> PIP
DATA --> MACP

The important architectural point is that these are different paths to the same logical data.

This is why path abstraction in configuration is essential.

10. Calibration and Production Separation

flowchart LR

subgraph Calibration["Manual Calibration / Maintenance"]
ROIUI["ROI Page"]
MASKDRAW["Mask drawing on Mac"]
ROIADJ["ROI Adjustment"]
MASKGEN["Polygon / mask generation"]
end

subgraph Production["Automated Production Pipeline"]
SNAP["Snapshot + rectify"]
CROP["Crop bins"]
ONNX["Detect bottles"]
CMP["Compare inventory"]
end

CFG["Persisted configuration + polygons"]

ROIUI --> CFG
MASKDRAW --> ROIADJ
ROIADJ --> CFG
MASKGEN --> CFG

CFG --> SNAP
CFG --> CROP

SNAP --> CROP
CROP --> ONNX
ONNX --> CMP

This separation protects the production pipeline from accidental geometry changes.

Calibration updates references.
Production only reads them.

11. End-to-End Operational Architecture

flowchart LR

subgraph UserSide["User / Operator Side"]
KIOSK["Qt Kiosk on Pi"]
MAC["Mac tools"]
end

subgraph PiSide["Raspberry Pi Runtime"]
API["Backend API"]
WORKERS["Vision workers"]
CONFIG["Shared config"]
end

subgraph NASSide["Synology NAS"]
DATA["Shared operational data"]
end

KIOSK --> API
KIOSK --> CONFIG
WORKERS --> CONFIG
WORKERS --> DATA
API --> DATA
MAC --> DATA
MAC --> PiSide

This captures the practical operating model:

  • kiosk users interact mainly with the Pi
  • workers execute mainly on the Pi
  • large persistent artifacts live on the NAS
  • Mac is used for higher-comfort visual maintenance and development

12. Separation of Responsibilities

Repository Responsibilities

The code repository contains:

  • application logic
  • UI code
  • worker logic
  • orchestration
  • services
  • documentation source
  • configuration logic

It answers:

How does the system work?

Data Responsibilities

The shared data tree contains:

  • inputs
  • outputs
  • evidence
  • models
  • debug traces
  • artifacts generated by the code

It answers:

What did the system process and produce?

13. Why This Design Is Strong

This architecture has several benefits.

Operational resilience

NAS-backed data survives Pi rebuilds.

Clean repository

Large artifacts do not pollute the source tree.

Multi-device usability

Pi, NAS, and Mac can all participate in the workflow.

Safer calibration

Manual geometry work stays separated from production automation.

Better documentation

The repository documents the system, while the data tree documents actual runtime behavior.

14. Recommended Mental Model

flowchart LR

BRAIN["Repository
Logic / workflows / UI / services"]

MEMORY["Data tree
Images / models / outputs / evidence"]

BRAIN --> MEMORY

A useful project-level mental model is:

  • the repository is the brain
  • the data tree is the memory and evidence store

The repository defines behavior.
The data tree records execution artifacts and supports review.

15. Summary

The Wine Platform uses a deliberately distributed architecture:

Raspberry Pi

Runs the code repository and executes the system.

Synology NAS

Stores the persistent operational data.

Mac

Supports comfortable visual maintenance, debugging, and documentation.

Manual Lane

Handles operator workflows through the Qt kiosk and backend.

Automated Vision Lane

Processes snapshots, crops cells, runs ONNX detection, and compares counts.

This separation of code, data, and workstation roles is a major strength of the platform. It keeps the system maintainable, scalable, auditable, and practical for real cellar operations.