Repository and Data Layout¶

Overview¶

The Wine Platform is intentionally split into two major filesystem domains:

Code / application repository
Runtime data / shared storage

This separation is a key architectural principle of the project.

It keeps:

source code versioned and deployable
runtime outputs persistent and shareable
large image/model assets outside the main code repository
Raspberry Pi execution decoupled from NAS-backed storage

In practice, the system is organized as:

Domain	Main Location	Purpose
Code	`/home/pi/wine_platform`	application code, docs, tools, services
Data	`/mnt/nasWeb/web_images/Stock_vision` on Pi, `/volume2/web/web_images/Stock_vision` on NAS	snapshots, crops, models, proposals, runtime vision artifacts

1. High-Level Separation: Code vs Data¶

Code Repository¶

The code repository contains:

backend API
Qt kiosk frontend
vision workers
shared configuration
tools
documentation
service definitions

This is the software structure of the project.

Main path on Raspberry Pi:

/home/pi/wine_platform

Data Repository¶

The data area contains:

images
models
proposals
snapshots
crop outputs
runtime debug artifacts

This is the operational working area of the project.

Main path on Synology NAS:

/volume2/web/web_images/Stock_vision

Mounted on Raspberry Pi as:

/mnt/nasWeb/web_images/Stock_vision

This means the same runtime data is visible:

directly on the NAS
through the Pi mount path
potentially from macOS via SMB mount

2. Why This Separation Exists¶

The project separates code and data for several practical reasons.

2.1 Version-Control Safety¶

Source code should be stored in Git and evolve cleanly.

Runtime data such as:

snapshots
crop results
model artifacts
temporary debug files

should not clutter the code repository.

2.2 Persistent Operational Storage¶

The NAS is the correct place for:

large image archives
model files
generated proposals
long-lived runtime outputs

This ensures the data survives:

Raspberry Pi rebuilds
OS reinstalls
local storage issues

2.3 Shared Accessibility¶

The data area can be accessed from multiple environments:

Environment	Path Style
Synology NAS	`/volume2/web/web_images/...`
Raspberry Pi	`/mnt/nasWeb/web_images/...`
macOS SMB mount	`/Volumes/web/...`

This is especially useful for:

manual mask creation
ROI adjustment
documentation screenshots
debugging vision outputs from a larger screen

3. Code Repository Structure¶

Based on the repository tree on the Raspberry Pi, the main source structure is:

/home/pi/wine_platform/
|-- apps
|   `-- winecellar
|       |-- backend
|       `-- frontend
|-- docs
|-- shared
|-- systemd
|-- tools
`-- workers
    `-- wine_inventory

4. Code Repository Domains¶

4.1 `apps/`¶

This contains the Wine Cellar application layer.

`apps/winecellar/backend`¶

Backend application code:

API routers
schemas
models
services
core backend logic

./wine_platform/apps/
    |-- winecellar
        |-- .venv
        |-- backend
        |   `-- app
        |       |-- api
        |       |   |-- routers
        |       |   `-- schemas
        |       |-- core
        |       |-- models
        |       `-- services
        `-- frontend
            `-- qt_kiosk
                |-- pages
                `-- widgets

This is the operational application server used by the manual lane.

`apps/winecellar/frontend/qt_kiosk`¶

Qt-based kiosk user interface:

pages
widgets
manual inventory flows
shelf page
ROI calibration page

This is the touch-first UI running on the Raspberry Pi screen.

4.2 `workers/`¶

This contains the automated vision lane.

`workers/wine_inventory/src/pince_shelf`¶

This is the core vision worker package and includes:

cli
config
integration
roi
utils
vision

This is where the automated stock detection pipeline lives.

It contains modules such as:

snapshot capture
rectification
crop generation
ONNX inference
DB comparison
motion/scheduled integration

4.3 `shared/`¶

Shared runtime support for both manual and automated lanes.

Subareas include:

`shared/config`¶

Centralized configuration used across the project.

Includes:

environment files
pince_shelf.ini
templates for corner tracking

`shared/logs`¶

Centralized logs.

`shared/run`¶

Runtime control files / process-related state.

`shared/state`¶

Persistent shared application state.

This directory is critical because it provides cross-lane configuration consistency.

4.4 `docs/`¶

Project documentation structure.

Subfolders include:

architecture
flows
ops
scripts

This reflects the architecture/documentation system you have been building.

4.5 `tools/`¶

Standalone support scripts such as:

repo-tree generation
documentation helpers
utility scripts

These are developer/operations tools rather than runtime business logic.

4.6 `systemd/`¶

Service definitions and deployment helpers for Raspberry Pi runtime orchestration.

5. Data Repository Structure¶

The data tree, visible on both NAS and Pi mount, looks like this: :contentReference[oaicite:3]{index=3}

Stock_vision
`-- data
    |-- cells_runtime
    |   `-- crop_cells_debug
    |-- cells_runtime_res
    |-- models
    |-- proposals
    |   |-- evidence
    |   `-- out
    `-- snapshots
        |-- corner_json_history
        `-- tmp
            `-- shelf_debug

There are also sibling directories:

Label
docs

6. Data Area Domains¶

6.1 `Label/`¶

Stores label images.

This is likely shared with material/master data workflows where bottle or label images are captured and archived.

6.2 `Stock_vision/data/models`¶

Stores vision models.

This includes trained model artifacts such as ONNX files used by the detection pipeline.

This is intentionally kept outside the code repo because:

models are large
models may change independently of code
deployment may vary by environment

6.3 `Stock_vision/data/snapshots`¶

Stores snapshot-related artifacts.

This is one of the most important runtime directories.

It includes:

accepted raw snapshots
rectified shelf images
corner history
temporary/debug outputs

`corner_json_history`¶

Stores persisted corner-point tracking history used for smoothing and stabilization across runs.

`tmp/shelf_debug`¶

Stores debug images for snapshot acquisition and rectification.

Examples include: - ROI overlays - gradient debug images - warped shelf previews - capture-readiness diagnostics

6.4 `Stock_vision/data/cells_runtime`¶

Stores cell-level crop outputs.

This is the operational output directory for:

per-bin crops
crop-stage artifacts

`crop_cells_debug`¶

Contains crop overlays and crop-stage debug material.

6.5 `Stock_vision/data/cells_runtime_res`¶

Stores results generated after inference.

This likely includes:

ONNX detection outputs
annotated images
CSV reports
comparison outputs

This is essentially the post-crop / post-detection result zone.

6.6 `Stock_vision/data/proposals`¶

Stores proposal-related artifacts.

Subfolders:

`evidence`¶

Evidence files supporting proposals / review / operator decisions.

`out`¶

Proposal output files.

This area appears intended for higher-level stock discrepancy or review workflows.

6.7 `docs/` in NAS area¶

The NAS-side docs directory is separate from the code repository documentation.

This may be used for:

exported project documents
runtime-generated reports
externally accessible docs

This is conceptually different from:

/home/pi/wine_platform/docs

which is the source documentation repository.

7. Same Data, Different Paths¶

A very important operational detail is that the same shared data appears under different filesystem roots depending on the machine.

On Synology NAS¶

/volume2/web/web_images/Stock_vision

On Raspberry Pi¶

/mnt/nasWeb/web_images/Stock_vision

This means the system must distinguish between:

logical data identity
machine-local mount path

That is exactly why settings/path-resolution logic is so important in your project.

8. Architectural Meaning of the Split¶

This structure reflects the fact that Wine Platform is not a single-script project. It is a multi-lane system with different responsibilities.

Manual Lane¶

Located mostly in:

apps/winecellar/frontend
apps/winecellar/backend

Responsibilities:

user interaction
material management
goods movements
inventory workflows
shelf UI
calibration UI

Automated Vision Lane¶

Located mostly in:

workers/wine_inventory/src/pince_shelf

Responsibilities:

image acquisition
rectification
cropping
inference
comparison
motion/scheduled execution

Shared Runtime Foundation¶

Located mostly in:

shared/

Responsibilities:

common config
common state
common templates
logs and runtime support

Shared Operational Data¶

Located mostly in NAS-backed storage:

.../web_images/Stock_vision/data

Responsibilities:

runtime image artifacts
models
crop results
review evidence
reproducible vision pipeline inputs/outputs

9. Practical Interpretation for Development¶

Code changes¶

When you modify:

Python modules
Qt pages
backend logic
tools
docs

you are working inside:

/home/pi/wine_platform

Runtime vision inspection¶

When you inspect:

snapshots
masks
crops
results
debug images
models

you are working inside:

/volume2/web/web_images/Stock_vision

or its mounted equivalent.

Mac-based visual work¶

For tasks such as:

mask drawing
ROI adjustment
reviewing debug artifacts

you typically access the NAS-mounted data tree from macOS.

That is data work, not code work.

10. Recommended Mental Model¶

A useful way to think about the project is:

Repository = Brain¶

Contains:

logic
workflows
configuration code
services
UI
automation scripts

Data Tree = Memory + Evidence¶

Contains:

images
runtime outputs
debug traces
trained models
proposals
review artifacts

The code decides what to do.
The data tree shows what happened.

11. Summary¶

The Wine Platform filesystem layout is intentionally split between:

Code Repository¶

/home/pi/wine_platform

Purpose: - application source - workers - shared config - docs - tools - services

Shared Data Repository¶

/volume2/web/web_images/Stock_vision
/mnt/nasWeb/web_images/Stock_vision

Purpose: - snapshots - crop outputs - debug artifacts - trained models - proposals - label images

This separation makes the system:

easier to maintain
easier to document
more resilient to device rebuilds
better suited for mixed Pi / NAS / Mac workflows
cleaner from both software-architecture and operational perspectives

Repository and Data Layout¶

Overview¶

1. High-Level Separation: Code vs Data¶

Code Repository¶

Data Repository¶

2. Why This Separation Exists¶

2.1 Version-Control Safety¶

2.2 Persistent Operational Storage¶

2.3 Shared Accessibility¶

3. Code Repository Structure¶

4. Code Repository Domains¶

4.1 apps/¶

apps/winecellar/backend¶

apps/winecellar/frontend/qt_kiosk¶

4.2 workers/¶

workers/wine_inventory/src/pince_shelf¶

4.3 shared/¶

shared/config¶

shared/logs¶

shared/run¶

shared/state¶

4.4 docs/¶

4.5 tools/¶

4.6 systemd/¶

5. Data Repository Structure¶

6. Data Area Domains¶

6.1 Label/¶

6.2 Stock_vision/data/models¶

6.3 Stock_vision/data/snapshots¶

corner_json_history¶

tmp/shelf_debug¶

6.4 Stock_vision/data/cells_runtime¶

crop_cells_debug¶

6.5 Stock_vision/data/cells_runtime_res¶

6.6 Stock_vision/data/proposals¶

evidence¶

out¶

6.7 docs/ in NAS area¶

7. Same Data, Different Paths¶

On Synology NAS¶

On Raspberry Pi¶

8. Architectural Meaning of the Split¶

Manual Lane¶

Automated Vision Lane¶

Shared Runtime Foundation¶

Shared Operational Data¶

9. Practical Interpretation for Development¶

Code changes¶

Runtime vision inspection¶

Mac-based visual work¶

10. Recommended Mental Model¶

Repository = Brain¶

Data Tree = Memory + Evidence¶

11. Summary¶

Code Repository¶

Shared Data Repository¶

4.1 `apps/`¶

`apps/winecellar/backend`¶

`apps/winecellar/frontend/qt_kiosk`¶

4.2 `workers/`¶

`workers/wine_inventory/src/pince_shelf`¶

4.3 `shared/`¶

`shared/config`¶

`shared/logs`¶

`shared/run`¶

`shared/state`¶

4.4 `docs/`¶

4.5 `tools/`¶

4.6 `systemd/`¶

6.1 `Label/`¶

6.2 `Stock_vision/data/models`¶

6.3 `Stock_vision/data/snapshots`¶

`corner_json_history`¶

`tmp/shelf_debug`¶

6.4 `Stock_vision/data/cells_runtime`¶

`crop_cells_debug`¶

6.5 `Stock_vision/data/cells_runtime_res`¶

6.6 `Stock_vision/data/proposals`¶

`evidence`¶

`out`¶

6.7 `docs/` in NAS area¶