# enkhbold0519/omnicave architecture

> Architecture diagram of the GitHub repository enkhbold0519/omnicave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enkhbold0519/omnicave
- Repository: https://github.com/enkhbold0519/omnicave

## Overview

OmniCave is a multi-device wine-cellar management product: users manage cellars and bottles, inspect physical locations and conditions, and access AI assistance through a display and companion apps. The primary visible flow is display interaction through its API client to backend routes, which dispatch to inventory, vision, and service logic backed by a database. Separate capability branches cover environmental monitoring, recommendations, critic dialogue, briefings, and collection valuation. The README documents the broader ecosystem; some subsystem links are therefore documented rather than verified in sampled implementation.

Main entry points: [`backend/app/routes.py`](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/routes.py) (Route dispatch), [`backend/app/services.py`](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/services.py) (Account and business services), [`backend/app/main.py`](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/main.py) (HTTP API), [`webos/wine-cellar-display/src/App.tsx`](https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/App.tsx) (Display interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_display["Integrated display"]
  node_display_app["Display interface<br/>[App.tsx]"]
  node_api_client["Display API client<br/>[api.ts]"]
  node_review["Detection review"]
end

subgraph group_backend["Cellar backend"]
  node_backend_api["HTTP API<br/>[main.py]"]
  node_route_dispatch["Route dispatch<br/>[routes.py]"]
  node_inventory["Cellars and bottles<br/>[inventory.py]"]
  node_geometry["Cellar geometry<br/>[geometry.py]"]
  node_database[("Cellar database<br/>[db.py]")]
  node_vision["Bottle recognition<br/>[vision.py]"]
  node_devices["Devices and sensors<br/>[devices.py]"]
  node_environment["Environmental monitoring<br/>[simulator.py]"]
  node_services["Account and business services<br/>[services.py]"]
end

subgraph group_intelligence["AI and insights"]
  node_recommendations["Wine recommendations<br/>[services.py]"]
  node_critic_dialogue["Critic dialogue<br/>[tasting.py]"]
  node_llm_client["LLM client<br/>[llm.py]"]
  node_llm_provider{{"LLM provider"}}
  node_news_briefing["Wine briefing<br/>[news.py]"]
  node_market_value["Market valuation<br/>[market.py]"]
end

subgraph group_clients["Companion clients"]
  node_ios_app["iOS companion<br/>[Views.swift]"]
end

node_user(("Cellar user"))
node_mobile_user(("Mobile user"))

node_user -->|"uses"| node_display_app
node_display_app -->|"calls"| node_api_client
node_api_client -->|"requests"| node_backend_api
node_display_app -->|"presents"| node_review
node_review -->|"confirms detection"| node_api_client
node_backend_api -->|"dispatches"| node_route_dispatch
node_route_dispatch -->|"routes cellar requests"| node_inventory
node_route_dispatch -->|"routes service requests"| node_services
node_route_dispatch -->|"routes vision requests"| node_vision
node_inventory -->|"reads and writes"| node_database
node_inventory -->|"uses placement logic"| node_geometry
node_route_dispatch -->|"routes device requests"| node_devices
node_backend_api -->|"initializes"| node_database
node_backend_api -->|"starts and stops"| node_environment
node_services -->|"uses persistence"| node_database
node_services -->|"requests generation"| node_llm_client
node_services -->|"provides"| node_recommendations
node_route_dispatch -->|"routes dialogue"| node_critic_dialogue
node_critic_dialogue -->|"generates dialogue"| node_llm_client
node_llm_client -->|"streams completions"| node_llm_provider
node_services -->|"aggregates news"| node_news_briefing
node_services -->|"uses market data"| node_market_value
node_mobile_user -->|"uses"| node_ios_app
node_ios_app -.->|"synchronizes with"| node_backend_api
node_devices -.->|"provides monitoring"| node_environment

click node_display_app "https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/App.tsx"
click node_api_client "https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/api.ts"
click node_review "https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/components/ReviewDetection.tsx"
click node_backend_api "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/main.py"
click node_route_dispatch "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/routes.py"
click node_inventory "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/inventory.py"
click node_geometry "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/geometry.py"
click node_database "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/db.py"
click node_vision "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/vision.py"
click node_devices "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/devices.py"
click node_environment "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/simulator.py"
click node_services "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/services.py"
click node_recommendations "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/services.py"
click node_critic_dialogue "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/tasting.py"
click node_llm_client "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/llm.py"
click node_news_briefing "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/news.py"
click node_market_value "https://github.com/enkhbold0519/omnicave/blob/main/backend/app/market.py"
click node_ios_app "https://github.com/enkhbold0519/omnicave/blob/main/Mobile/ios/OmniCave/Views.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_display_app,node_api_client,node_review,node_user,node_mobile_user toneBlue
class node_backend_api,node_route_dispatch,node_inventory,node_geometry,node_database,node_vision,node_devices,node_environment,node_services toneAmber
class node_recommendations,node_critic_dialogue,node_llm_client,node_llm_provider,node_news_briefing,node_market_value toneMint
class node_ios_app toneRose
```

## Components

### Integrated display

- [Display interface](https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/App.tsx): `webos/wine-cellar-display/src/App.tsx`
- [Display API client](https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/api.ts): `webos/wine-cellar-display/src/api.ts`
- [Detection review](https://github.com/enkhbold0519/omnicave/blob/main/webos/wine-cellar-display/src/components/ReviewDetection.tsx): `webos/wine-cellar-display/src/components/ReviewDetection.tsx`

### Cellar backend

- [HTTP API](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/main.py): `backend/app/main.py`
- [Route dispatch](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/routes.py): `backend/app/routes.py`
- [Cellars and bottles](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/inventory.py): `backend/app/inventory.py`
- [Cellar geometry](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/geometry.py): `backend/app/geometry.py`
- [Cellar database](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/db.py): `backend/app/db.py`
- [Bottle recognition](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/vision.py): `backend/app/vision.py`
- [Devices and sensors](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/devices.py): `backend/app/devices.py`
- [Environmental monitoring](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/simulator.py): `backend/app/simulator.py`
- [Account and business services](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/services.py): `backend/app/services.py`

### AI and insights

- [Wine recommendations](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/services.py): `backend/app/services.py`
- [Critic dialogue](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/tasting.py): `backend/app/tasting.py`
- [LLM client](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/llm.py): `backend/app/llm.py`
- **LLM provider**
- [Wine briefing](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/news.py): `backend/app/news.py`
- [Market valuation](https://github.com/enkhbold0519/omnicave/blob/main/backend/app/market.py): `backend/app/market.py`

### Companion clients

- [iOS companion](https://github.com/enkhbold0519/omnicave/blob/main/Mobile/ios/OmniCave/Views.swift): `Mobile/ios/OmniCave/Views.swift`

### Other components

- **Cellar user**
- **Mobile user**

## Connections

- Cellar user → Display interface: uses (evidence: `README.md`)
- Display interface → Display API client: calls (evidence: `webos/wine-cellar-display/src/App.tsx`)
- Display API client → HTTP API: requests (evidence: `README.md`)
- Display interface → Detection review: presents (evidence: `webos/wine-cellar-display/src/App.tsx`)
- Detection review → Display API client: confirms detection (evidence: `webos/wine-cellar-display/src/components/ReviewDetection.tsx`)
- HTTP API → Route dispatch: dispatches (evidence: `backend/app/main.py`)
- Route dispatch → Cellars and bottles: routes cellar requests (evidence: `backend/app/routes.py`)
- Route dispatch → Account and business services: routes service requests (evidence: `backend/app/routes.py`)
- Route dispatch → Bottle recognition: routes vision requests (evidence: `backend/app/routes.py`)
- Cellars and bottles → Cellar database: reads and writes (evidence: `backend/app/inventory.py`)
- Cellars and bottles → Cellar geometry: uses placement logic (evidence: `backend/app/inventory.py`)
- Route dispatch → Devices and sensors: routes device requests (evidence: `backend/app/routes.py`)
- HTTP API → Cellar database: initializes (evidence: `backend/app/main.py`)
- HTTP API → Environmental monitoring: starts and stops (evidence: `backend/app/main.py`)
- Account and business services → Cellar database: uses persistence (evidence: `backend/app/services.py`)
- Account and business services → LLM client: requests generation (evidence: `backend/app/services.py`)
- Account and business services → Wine recommendations: provides (evidence: `README.md`)
- Route dispatch → Critic dialogue: routes dialogue (evidence: `backend/app/routes.py`)
- Critic dialogue → LLM client: generates dialogue (evidence: `README.md`)
- LLM client → LLM provider: streams completions (evidence: `backend/app/llm.py`)
- Account and business services → Wine briefing: aggregates news (evidence: `backend/app/services.py`)
- Account and business services → Market valuation: uses market data (evidence: `backend/app/services.py`)
- Mobile user → iOS companion: uses (evidence: `README.md`)
- iOS companion → HTTP API: synchronizes with (evidence: `README.md`)
- Devices and sensors → Environmental monitoring: provides monitoring (evidence: `README.md`)
