yuheng

YuHeng(玉衡 Jade Balance) - A local nutrition tracking app named after the fifth and brightest star in the Big Dipper constellation in traditional Chinese astronomy. Just as this star serves as a guiding and balancing force, YuHeng aims to help users in tracking their nutrition effectively.

Features

📸 Photo-based food logging
🤖 Auto-recognition of dishes using Gemini/OpenAI/Compatible LLMs
📊 Daily nutrition stats & weekly history
🍽️ Support for backfilling meals (Breakfast, Lunch, Dinner, Snack)
🐳 Docker support with persistent DB (SQLite & PostgreSQL)
⚡ Asynchronous image recognition queue
⚖️ Unit conversion (kcal/kJ, g/oz)
⏰ Custom meal times configuration
👥 Meal sharing & portion splitting
🔍 Packaged food scanning & recognition

Supported LLM Providers

YuHeng supports a wide range of LLM providers for food recognition:

Google Gemini: Optimized for vision tasks (Gemini 2.5 Flash, Gemini 3 Flash/Pro).
Zhipu AI: Support for GLM-4V models.
OpenAI: GPT-4o and GPT-4o mini.
OpenAI Compatible: Support for various providers like DeepSeek, Qwen-VL, GLM-4V, Doubao, etc.

Detailed model lists can be configured in the settings page.

Getting Started

Clone the repo
Run bun install
Run bun run dev
Open http://localhost:3000
Configure your LLM Provider and API Key in the settings page.

Docker Usage

Build the image:

docker build -t yuheng .

Run the container:

# Create a data directory
mkdir data

# Run container with PostgreSQL
docker run -d \
  --name yuheng \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://user:password@your-db-host:5432/yuheng \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/formaxcn/yuheng

The container will automatically run database migrations on startup.

Environment Variables

Variable	Description	Required	Default
`DATABASE_URL`	PostgreSQL connection string	Yes	-

Example:

DATABASE_URL=postgresql://user:password@localhost:5432/yuheng

Docker Compose (PostgreSQL)

You can easily start YuHeng with a PostgreSQL database using Docker Compose:

Run:
```
docker-compose up -d
```
This will start both the YuHeng app and a PostgreSQL database. The app will automatically wait for the database to be ready and run migrations before starting.